start

Start Process Job

Resolve <plugin-root> as two directories above this SKILL.md.

Never search memory for CPJ work; use validated CPJ state.

The user-visible parent owns every CPJ launch and completion. Never delegate local process execution, launch, waiting, monitoring, or CPJ ownership to a spawned subagent. A subagent can analyze independent material only.

Launch exactly once

Prefer direct argv:

node "<plugin-root>/scripts/job.mjs" start \
  --name "<label>" --cwd "<working-directory>" --json -- \
  <command> [args...]

Use fixed non-login Bash only for a validated shell composition:

node "<plugin-root>/scripts/job.mjs" start \
  --name "<label>" --cwd "<working-directory>" --shell --json -- \
  '<single finite foreground command>'

All controller options, including --json, MUST precede --; that separator ends controller parsing. Shell mode requires exactly one command string after it. Never use eval.

CPJ writes private durable state under ${CODEX_HOME:-$HOME/.codex}/process-jobs. Before the first controller call, use the host permission context instead of probing the filesystem. If that directory is not writable in the current sandbox, request sandbox_permissions: "require_escalated" on the first call with a narrow justification and, when supported, prefix ["node", "<plugin-root>/scripts/job.mjs"]. Do not waste a call on a predictable EPERM, weaken the sandbox, or edit Codex configuration.

Route and compose

Use CPJ when the user asks to detach/background work, or when a finite local workload may exceed about 60 seconds, has uncertain duration, should survive a client exit, or merits later lightweight status checks.

Classify the underlying workload from context, not its executable name. A qualifying script, download, inference runner, or wrapper uses its original foreground payload through CPJ. Honor an explicit user request to keep work in the foreground.

Exclude quick commands, interactive stdin, servers/watchers, intentional daemons, remote/external services, and fire-and-exit launchers. The tracked process must remain in the foreground until the real workload ends.

Task-specific skills own command construction, preflight checks, arguments, and correctness gates. CPJ owns execution lifecycle for qualifying finite local workloads. Preserve a validated foreground argv or shell string. If a workflow emits a detached launcher, do not pass that launcher through CPJ unchanged: prefer its foreground payload, or a supported mode that remains alive until the workload finishes and propagates its terminal status. Otherwise leave it with its external lifecycle owner.

Required choices

• Require a concrete command and cwd; never invent consequential arguments.
• Default to direct argv. Use --shell for Bash features and --posix-sh only for intentionally portable POSIX syntax.
• Add --critical for repair, firmware, migration, destructive conversion, or any operation whose interruption could worsen state.
• Add --goal-mode only when this command belongs to an explicitly active Codex Goal. If unclear and get_goal exists, check once; never inspect private Goal storage or infer Goal mode from repeated turns.
• Optional controller flags before --: --no-notify, --notify-user, --no-notify-user, and --json.

Detached work receives no interactive stdin. Resolve passwords, confirmations, sudo, or Polkit in the foreground first and prefer non-interactive checks such as sudo -n. --shell requires /bin/bash and must remain compatible with macOS Bash 3.2. Never put secrets in argv or tracked logs.

For storage repair, preserve the evidenced target device, mount state, and flags. Never infer a device node from its name.

Hard turn boundary

Treat a successful controller return as a hard launch-turn release boundary. Do not read the status skill or call status, tail, result, --wait, write_stdin, sleep, ps, or another process probe in the launch turn. Result-dependent work resumes through completion delivery, a later user-initiated turn, or a later automatic continuation of an explicitly active Goal. If the same user request includes independent work, continue only that independent work.

This boundary has no same-turn wait exception. A request to report the final result when it finishes is an eventual-delivery request, not permission to keep the launch turn open. If the user explicitly requires foreground execution in the same turn, do not use CPJ for that command. State the tradeoff and run the foreground command only with the user's approval. Never substitute polling.

Report and stop

Name this workflow Codex Process Jobs, never a detached-job skill or workflow. Before launch, use at most one short sentence: say that Codex Process Jobs will run it in the background and hand back immediately. Do not narrate procedure, payload, argv, cwd, controller mechanics, metadata, or validation.

After success, use no more than two short sentences: identify the background job ID, then say that a completion notification and any requested summary should appear when it finishes; status is available on request. If delivery is unavailable or disabled, say completion is recorded and status/result is available. Never promise an immediate wake.

For --goal-mode, say the job is durably tracked under the Goal and will be picked up by completion delivery or Goal continuation. Automatic continuation is not permission to monitor: do independent work or apply the host Goal blocked audit.

A job is machine-scoped and survives Codex App, IDE, or CLI exit. Never add session-exit cleanup. Critical jobs later require explicit approval and $cancel --force.