Function runViaEngine

engine/src/cli.ts:289–373

(prompt: string)

 * a deliberate, recent act naming a kild that existed at the time. When the two disagree, the
 * deliberate act is the truer one.
 *
 * It is also the only ordering that survives the trap this was found in. A harness's settings
 * file can carry a kild id, that file is re-read on every start including resumes, and it
 * outranks anything a shell exports — so a stale entry pointing at an ARCHIVED kild is
 * invisible, unkillable from the shell, and drains nothing forever while reporting success.
 * Ranking it below an actual attach means a real attach always wins, and the stale value can
 * only ever be a fallback for a session that never attached at all.
 *
 * Pinning up front still works, which was the point of keeping the environment at all. Fields
 * resolve independently, so a hook that passes `--as` and lets the id resolve works too.
 */
async function resolveAttachment(
  id: string | undefined,
  handle: string | undefined,
): Promise<{ kildId?: string; handle?: string }> {
  if (id && handle) return { kildId: id, handle };
  const session = harnessSession();
  // Deliberately NOT guarded. An unreadable record means "there may be an attachment and I
  // cannot read it", and a `kild send` that swallowed that would post the message with no
  // credential — silently unattributed, which is the exact bug this file exists to fix. The
  // one caller allowed to degrade to silence is the turn-end hook, and it does so at its own
  // call site where it knows it is a hook.
  const record = session ? await findAttachment(session) : null;
  return {
    kildId: id ?? record?.kildId ?? process.env.KILD_KILD_ID ?? undefined,
    handle: handle ?? record?.handle ?? process.env.KILD_HANDLE ?? undefined,
  };
}

/** `kild attach <id> --as <handle>` — register an ATTACHED agent: a harness kild
 *  does not own (the Claude Code session you are driving) claiming a `@handle` in the
 *  kild. Nothing is spawned; the handle is addressable immediately. Idempotent.
 *
 *  The attachment is also recorded against this session's own id, which is what lets the
 *  session find its handle again later without carrying it in the environment. That is the
 *  whole of what makes attaching mid-session work: a process's environment is fixed at exec
 *  time, so a session opened before the kild existed can never be told about it any other
 *  way. The token is deliberately NOT recorded — it dies with the engine, so a copy on disk
 *  would go stale and be rejected; `send` mints a fresh one from the idempotent attach. */
async function kildAttach(id: string | undefined): Promise<void> {
  const handle = values.as;
  if (!id || !handle) throw new Error('usage: kild attach <id> --as <handle>');
  const result = await attachAgent(id, handle);
  const session = harnessSession();
  if (session) await recordAttachment(session, id, handle);
  console.log(json ? JSON.stringify(result, null, 2) : result.message);
}

/**
 * `kild inbox <id> --as <handle> [--format claude-stop]` — destructively read that
 * agent's inbox. An empty drain is also its idle signal; there is no status verb.
 *
 * With `--format claude-stop` this IS a Claude Code Stop hook's entire body, so it obeys
 * the hook contract absolutely: print the block JSON when mail is waiting, print **nothing
 * at all** when it is not, and **exit 0 either way** — including when the engine is down,
 * the kild is gone, or the handle was never attached. A hook that cannot reach kild must
 * never stop the operator from finishing a turn. Without the flag it is an ordinary CLI
 * verb and failures are ordinary loud errors.