Scheduled jobs

A scheduled Kin job is a host scheduler invoking kin -p in the workspace where the work and its authority already live. Kin owns one headless run; cron, systemd, launchd, CI, or another operator-selected scheduler owns timing, availability, environment, retries, and whole-process isolation.

Start with a deterministic command

Before asking an agent to do recurring work, check whether a script or task can produce the result directly. A deterministic command is easier to test, observe, retry, and constrain. Use kin -p when the job genuinely needs the peer to inspect context, reason about changing evidence, or use Kin’s bounded tools.

Run the command manually from the intended working directory first:

cd /path/to/workspace
kin -p "Reconcile the new evidence and update the current account."

A scheduler should set that directory explicitly rather than depending on its default launch directory.

Cron example

Create .kin/reports/ in the workspace first (mkdir -p .kin/reports). This example then runs at 03:05 each day and records the report and stderr:

5 3 * * * cd /path/to/workspace && /home/you/.local/bin/kin -p "Run the daily reconciliation. Verify the result and leave the workspace reviewable." --output .kin/reports/daily.md >> .kin/reports/daily.log 2>&1

Use absolute paths. Scheduler environments are usually smaller than an interactive shell, so provide the required PATH, provider variables, and other non-secret configuration through the scheduler’s normal mechanism. Keep credentials in their owning protected store; do not paste them into the prompt or crontab.

The same shape applies to a systemd service/timer, a launchd job, or CI: select the workspace, establish the intended environment, invoke one kin -p process, and retain its exit status and bounded output.

Each fire is a fresh turn

Every invocation starts a fresh Kin process and one headless turn. Do not rely on hidden process memory from a previous fire. Put cross-run truth in visible workspace files: source, tests, decision records, status boards, or another artifact whose owner and review rules are clear.

A job may use --resume <session-id> when continuation is explicitly part of the design, but the same conversation lease applies as in interactive Kin. Concurrent writers to one saved conversation fail closed. For most recurring jobs, a fresh turn against visible workspace state is simpler and more honest.

Trust and permissions

Headless Kin cannot establish workspace trust. Launch Kin interactively in the exact workspace first and persist trust there; a scheduler run without that DR 0218 precondition exits before model or tool work.

Headless permission gates fail closed because no person is present to answer. If a tool reaches an ASK decision or the model calls ask, the run records a structured needs-human item, performs no gated action, and exits with status 2. Do not weaken trust or permissions merely to make a schedule green.

On a machine that runs the per-user session service, a job may opt in with kin -p --attach instead: the same exit-2 outcome, but the question or approval stays live in the service as the exact pending block, so a person can later attach (kin --attach --resume <id>) or claim it from an OS surface and answer it — the original turn then continues. --idle SECONDS is the wait window. See Headless runs.

Exit codes and observation

kin -p has a small process contract:

Code	Meaning
0	The run completed cleanly and needs no human.
1	The run failed or stopped at a guard such as a turn, token, context, or loop limit.
2	The run needs human approval or input; the gated action did not run.

When --output report.md is present, Kin writes a Markdown report and a machine-readable report.md.json sidecar. A scheduler should branch on the exit code and may inspect the sidecar for status, usage, errors, and structured needs-human details. Do not parse model prose to decide whether the job succeeded.

Availability is the host’s promise

A laptop that is asleep or powered off does not run cron. A CI runner may be queued or unavailable. A systemd timer may apply its own catch-up policy. Kin does not provide a scheduler, job store, overlap policy, or retry daemon.

Choose a host whose availability matches the importance of the work, then use that host’s ordinary observation and recovery tools. If missed-run recovery, mutual exclusion, or retry policy matters, configure it in the scheduler or in a deterministic wrapper around kin -p.

Related guides

• Headless mode
• Modes and permissions
• Sessions