@hwip/cli 0.1.10 → 0.1.12

package/dist/schedule.js

@@ -3,20 +3,26 @@
  * Scheduled sessions (F8): what a schedule is, when it comes due, and the files it lives in.
  *
  * A schedule is one file, `<stateDir>/schedules/<id>.json` (0600). `hwip schedule` writes and
- * deletes them, the listener only reads them, and nothing reads-then-rewrites a file, so the two
- * never lose each other's change. What the listener has done about each one lives in its own file
+ * deletes them, the listener only reads them — except a `once` schedule that has run, which the listener
+ * deletes — and nothing reads-then-rewrites a file, so the two never lose each other's change. What the listener has done about each one lives in its own file
  * (`schedule-state.json`, `schedule-runner.ts`).
  *
  * Everything here is pure or touches only that directory. The clock is a parameter.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeScheduleState = exports.readScheduleState = exports.scheduleStatePath = exports.removeSchedule = exports.scheduleAnchor = exports.updateSchedule = exports.addSchedule = exports.listSchedules = exports.schedulesDir = exports.validateSchedule = exports.isScheduleId = exports.nextOccurrence = exports.occurrencesBetween = exports.parseWhen = exports.parseDuration = exports.WEEKDAYS = exports.ALL_DAYS = exports.DAY_NAMES = exports.defaultMaxRuntimeMin = exports.MAX_SCHEDULES = void 0;
+exports.writeScheduleState = exports.readScheduleState = exports.scheduleStatePath = exports.removeSchedule = exports.scheduleAnchor = exports.pastWhen = exports.updateSchedule = exports.addSchedule = exports.listSchedules = exports.schedulesDir = exports.validateSchedule = exports.isScheduleId = exports.nextOccurrence = exports.occurrencesBetween = exports.parseWhen = exports.parseDuration = exports.WEEKDAYS = exports.ALL_DAYS = exports.DAY_NAMES = exports.defaultMaxRuntimeMin = exports.MAX_SCHEDULES = exports.SCHEDULE_SESSION_CAPABILITY = void 0;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const gate_js_1 = require("./gate.js");
 const private_files_js_1 = require("./private-files.js");
 const replace_file_js_1 = require("./replace-file.js");
+/**
+ * Advertised in the listener's presence (`device-presence.ts`): this build runs `once` schedules and schedules into a
+ * session (`target: 'session'`). An older listener refuses both as fields it does not know, so the apps offer them only
+ * to a computer that lists this.
+ */
+exports.SCHEDULE_SESSION_CAPABILITY = 'schedule-session-v1';
 const isErrno = (err, code) => err instanceof Error && 'code' in err && err.code === code;
 const fail = (error) => ({ ok: false, error });
 exports.MAX_SCHEDULES = 20;
@@ -39,6 +45,9 @@ const DAY_NUMBER = Object.fromEntries(exports.DAY_NAMES.map((name, day) => [name
 exports.ALL_DAYS = [0, 1, 2, 3, 4, 5, 6];
 exports.WEEKDAYS = [1, 2, 3, 4, 5];
 const AT_TIME = /^([01]\d|2[0-3]):([0-5]\d)$/;
+const ON_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** An instant with its offset: a time without one would move with the machine's time zone. */
+const AT_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/;
 const parseDays = (raw) => {
     const word = raw.trim().toLowerCase();
     if (word === 'daily')
@@ -73,9 +82,33 @@ const parseEvery = (raw) => {
         return fail('--every must be at most 366 days');
     return { ok: true, value: minutes };
 };
-/** `--at HH:MM [--days …]` or `--every <N>m|<N>h`, not both and not neither. */
+/** `--on YYYY-MM-DD` and `--at HH:MM` as the instant that local date and time is. */
+const parseOnce = (on, at) => {
+    if (at === undefined)
+        return fail('--on needs --at HH:MM');
+    if (!AT_TIME.test(at.trim()))
+        return fail(`--at takes a 24-hour local time like 09:00 (got '${at}')`);
+    const date = ON_DATE.exec(on.trim());
+    const [year, month, day] = date ? [Number(date[1]), Number(date[2]) - 1, Number(date[3])] : [0, 0, 0];
+    const [hour, minute] = at.trim().split(':').map(Number);
+    const local = new Date(year, month, day, hour, minute);
+    // `Date` rolls an impossible day (Feb 30) into the next month; that is not the day that was asked for.
+    if (!date || local.getFullYear() !== year || local.getMonth() !== month || local.getDate() !== day) {
+        return fail(`--on takes a date like 2026-10-24 (got '${on}')`);
+    }
+    // And a time the clocks skip (spring forward) into the next hour.
+    if (local.getHours() !== hour || local.getMinutes() !== minute)
+        return fail(`${on} ${at.trim()} does not exist here: the clocks skip it`);
+    return { ok: true, value: { kind: 'once', at: local.toISOString() } };
+};
+/** `--at HH:MM [--days …]`, `--on YYYY-MM-DD --at HH:MM` or `--every <N>m|<N>h`, one of them and not neither. */
 const parseWhen = (input) => {
-    const { at, days, every } = input;
+    const { at, days, every, on } = input;
+    if (on !== undefined) {
+        if (days !== undefined || every !== undefined)
+            return fail('--on cannot be combined with --days or --every');
+        return parseOnce(on, at);
+    }
     if (every !== undefined) {
         if (at !== undefined || days !== undefined)
             return fail('--every cannot be combined with --at or --days');
@@ -122,6 +155,10 @@ const occurrencesBetween = (when, after, until, anchor) => {
     // A cursor read from a damaged state file may not be a number; the day walk below would never end on one.
     if (!Number.isFinite(after) || !Number.isFinite(until) || until <= after)
         return { count: 0, latest: null };
+    if (when.kind === 'once') {
+        const at = Date.parse(when.at);
+        return at > after && at <= until ? { count: 1, latest: at } : { count: 0, latest: null };
+    }
     if (when.kind === 'every') {
         const period = when.minutes * 60_000;
         const upTo = periodsSince(anchor, period, until);
@@ -145,8 +182,12 @@ const occurrencesBetween = (when, after, until, anchor) => {
     return { count, latest };
 };
 exports.occurrencesBetween = occurrencesBetween;
-/** The first time after `after` the schedule comes due; null for a `daily` with no days (a file `validateSchedule` would refuse). */
+/** The first time after `after` the schedule comes due; null for a `once` that is past and a `daily` with no days (a file `validateSchedule` would refuse). */
 const nextOccurrence = (when, after, anchor) => {
+    if (when.kind === 'once') {
+        const at = Date.parse(when.at);
+        return at > after ? at : null;
+    }
     if (when.kind === 'every') {
         const period = when.minutes * 60_000;
         return anchor + (periodsSince(anchor, period, after) + 1) * period;
@@ -163,7 +204,9 @@ exports.nextOccurrence = nextOccurrence;
 const SCHEDULE_ID = /^[a-z0-9]{6}$/;
 const LABEL = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const AGENT_KIND = /^[A-Za-z0-9_-]{1,32}$/;
-const KEYS = new Set(['v', 'id', 'createdAt', 'updatedAt', 'source', 'agentKind', 'cwd', 'label', 'session', 'wt', 'agentArgs', 'prompt', 'when', 'maxRuntimeMin']);
+const KEYS = new Set(['v', 'id', 'createdAt', 'updatedAt', 'source', 'agentKind', 'cwd', 'label', 'session', 'target', 'runId', 'wt', 'agentArgs', 'prompt', 'when', 'maxRuntimeMin']);
+/** A tmux `session_created`, as the registry keeps a run id. */
+const RUN_ID = /^\d{1,12}$/;
 const isScheduleId = (value) => typeof value === 'string' && SCHEDULE_ID.test(value);
 exports.isScheduleId = isScheduleId;
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -182,8 +225,14 @@ const checkWhen = (raw) => {
             return 'when has a field it does not know';
         return isInt(raw.minutes, MIN_EVERY_MIN, MAX_EVERY_MIN) ? null : `when.minutes must be a whole number of at least ${MIN_EVERY_MIN}`;
     }
+    if (raw.kind === 'once') {
+        if (Object.keys(raw).some((k) => k !== 'kind' && k !== 'at'))
+            return 'when has a field it does not know';
+        const wellFormed = typeof raw.at === 'string' && AT_INSTANT.test(raw.at) && Number.isFinite(Date.parse(raw.at));
+        return wellFormed ? null : 'when.at must be an ISO 8601 time with its offset';
+    }
     if (raw.kind !== 'daily')
-        return "when.kind must be 'daily' or 'every'";
+        return "when.kind must be 'daily', 'every' or 'once'";
     if (Object.keys(raw).some((k) => k !== 'kind' && k !== 'at' && k !== 'days'))
         return 'when has a field it does not know';
     if (typeof raw.at !== 'string' || !AT_TIME.test(raw.at))
@@ -203,7 +252,7 @@ const validateSchedule = (input) => {
     const unknownKey = Object.keys(input).find((k) => !KEYS.has(k));
     if (unknownKey !== undefined)
         return fail(`schedule has a field it does not know: ${unknownKey}`);
-    const { v, id, createdAt, updatedAt, source, agentKind, cwd, label, session, wt, agentArgs, prompt, when, maxRuntimeMin } = input;
+    const { v, id, createdAt, updatedAt, source, agentKind, cwd, label, session, target, runId, wt, agentArgs, prompt, when, maxRuntimeMin } = input;
     if (v !== 1)
         return fail('schedule.v must be 1');
     if (!(0, exports.isScheduleId)(id))
@@ -245,13 +294,29 @@ const validateSchedule = (input) => {
     }
     if (source === 'phone' && prompt === undefined)
         return fail('a schedule from the phone needs a prompt');
+    if (target !== undefined && target !== 'session')
+        return fail("schedule.target must be 'session' when given");
+    if (target === 'session') {
+        if (typeof runId !== 'string' || !RUN_ID.test(runId))
+            return fail('schedule.runId must be the run the session target types into');
+        if (prompt === undefined)
+            return fail('a schedule into a session needs a prompt');
+        if (wt !== undefined)
+            return fail('a schedule into a session carries no wt');
+        if (agentArgs !== undefined)
+            return fail('a schedule into a session carries no agentArgs');
+    }
+    else if (runId !== undefined) {
+        return fail("schedule.runId belongs to target 'session' only");
+    }
     const badWhen = checkWhen(when);
     if (badWhen)
         return fail(badWhen);
     const checkedWhen = when; // checkWhen accepted its shape
     if (!isInt(maxRuntimeMin, MIN_MAX_RUNTIME_MIN, MAX_MAX_RUNTIME_MIN))
         return fail(`schedule.maxRuntimeMin must be ${MIN_MAX_RUNTIME_MIN} to ${MAX_MAX_RUNTIME_MIN}`);
-    if (checkedWhen.kind === 'every' && maxRuntimeMin > checkedWhen.minutes)
+    // A session target has no runtime cap (the session is not the schedule's): its `maxRuntimeMin` bounds nothing.
+    if (checkedWhen.kind === 'every' && target !== 'session' && maxRuntimeMin > checkedWhen.minutes)
         return fail('schedule.maxRuntimeMin cannot be longer than the --every period');
     // Every field of `Schedule` was checked above; `input` is a record, which TypeScript cannot narrow field by field.
     return { ok: true, value: input };
@@ -326,6 +391,10 @@ const addSchedule = (make, newId = newScheduleId) => {
         const checked = (0, exports.validateSchedule)(schedule);
         if (!checked.ok)
             return { ok: false, error: checked.error };
+        // A `once` made after its time would never run: the runner counts from `createdAt`.
+        const past = (0, exports.pastWhen)(schedule.when, Date.parse(schedule.createdAt));
+        if (past)
+            return { ok: false, error: past };
         if (schedule.id !== id)
             return { ok: false, error: 'schedule.id is not the id it was made for' };
         try {
@@ -369,6 +438,9 @@ const updateSchedule = (id, change, now) => {
     const checked = (0, exports.validateSchedule)({ ...current, ...change, ...(retimed ? { updatedAt: new Date(now).toISOString() } : {}) });
     if (!checked.ok)
         return { ok: false, error: checked.error, failure: 'invalid' };
+    const past = retimed ? (0, exports.pastWhen)(checked.value.when, now) : null;
+    if (past)
+        return { ok: false, error: past, failure: 'invalid' };
     try {
         (0, replace_file_js_1.replaceFile)(schedulePath(id), `${JSON.stringify(checked.value, null, 2)}\n`, undefined, 0o600);
         return { ok: true, schedule: checked.value };
@@ -378,6 +450,9 @@ const updateSchedule = (id, change, now) => {
     }
 };
 exports.updateSchedule = updateSchedule;
+/** Why `when` cannot be given to a schedule at `now`: a `once` whose time has passed would never run. Null when it can. */
+const pastWhen = (when, now) => when.kind === 'once' && Date.parse(when.at) <= now ? 'that time has already passed' : null;
+exports.pastWhen = pastWhen;
 /** The time a schedule's runs are counted from: its last edit, else its creation. */
 const scheduleAnchor = (schedule) => Date.parse(schedule.updatedAt ?? schedule.createdAt);
 exports.scheduleAnchor = scheduleAnchor;
@@ -398,6 +473,8 @@ exports.removeSchedule = removeSchedule;
 // ── What the listener has done ───────────────────────────────────────
 const SCHEDULE_OUTCOMES = [
     'started', 'missed', 'overlap', 'busy', 'start_failed', 'missing_directory', 'unknown_agent', 'prompt_undelivered', 'prompt_unsupported', 'capped',
+    // A session target only: the run stayed busy past the wait, or it is over.
+    'session_busy', 'session_ended',
 ];
 const scheduleStatePath = () => (0, node_path_1.join)((0, gate_js_1.stateDir)(), 'schedule-state.json');
 exports.scheduleStatePath = scheduleStatePath;
@@ -408,10 +485,13 @@ const readRunState = (raw) => {
     if (!isRecord(raw) || !isNumber(raw.cursor))
         return null;
     const state = { cursor: raw.cursor };
-    const { running, last, pending } = raw;
+    const { running, delivering, last, pending } = raw;
     if (isRecord(running) && isSessionName(running.session) && isNumber(running.startedAt) && typeof running.promptPending === 'boolean') {
         state.running = { session: running.session, startedAt: running.startedAt, promptPending: running.promptPending, ...(running.capped === true ? { capped: true } : {}) };
     }
+    if (isRecord(delivering) && isSessionName(delivering.session) && isNumber(delivering.since)) {
+        state.delivering = { session: delivering.session, since: delivering.since };
+    }
     if (isRecord(last) && isOutcome(last.outcome) && isNumber(last.at))
         state.last = { outcome: last.outcome, at: last.at };
     if (isRecord(pending) && isNumber(pending.since) && isRecord(pending.counts)) {

package/dist/session-registry.d.ts

@@ -86,6 +86,11 @@ export declare const KNOWN_SESSION_TTL_MS: number;
  * runs were recorded) keys as the empty run.
  */
 export declare const runKey: (name: string, agentKind: string, runId?: string) => string;
+/**
+ * The registry file is there but would not read as a list: what `knownSessions` returns then is not all there is
+ * (it reads as empty). No file yet is not unreadable.
+ */
+export declare const registryUnreadable: () => boolean;
 /** Sessions this machine has seen, newest first, expired ones dropped. */
 export declare const knownSessions: (now?: number) => KnownSession[];
 /** One remembered session, or null when this machine never saw that name.
@@ -118,8 +123,34 @@ export declare const MAX_TMUX_RUNS_PER_RUN = 10;
  * — a fresh start `/resume`d into an old conversation keeps what it wrote first.
  */
 export declare const continuedRunId: (entries: readonly KnownSession[], name: string, agentKind: string, tmuxRunId: string, conversationId: string | null | undefined) => string;
-/** The run going on in tmux session `tmuxRunId` of `name`: the one it was joined to, else its own. */
-export declare const runOfTmuxSession: (name: string, tmuxRunId: string, now?: number) => string;
+/** The run going on in tmux session `tmuxRunId` of `name`: the one it was joined to, else its own. `known` is the registry as read. */
+export declare const runOfTmuxSession: (name: string, tmuxRunId: string, now?: number, known?: KnownSession[]) => string;
+/** How long after a schedule is tied to a run the registry may still be without a record of it (the listener's sweep writes it). */
+export declare const UNRECORDED_RUN_GRACE_MS: number;
+/** What tmux is asked to find a run: `liveSessionNames` and `liveRunIdOf` (`tmux-liveness.ts`), passed in so this file stays free of tmux. */
+export interface TmuxRuns {
+    /** Every session name tmux holds; null when no tmux answered. */
+    names: () => string[] | null;
+    /** The `session_created` of the tmux session under `name`; null when there is none, undefined when tmux did not answer. */
+    runIdOf: (name: string) => string | null | undefined;
+}
+/** Where a run is now: the tmux session it goes on in, `ended` when tmux answered and none holds it, `unknown` when tmux could not say. */
+export type RunWhereabouts = {
+    name: string;
+} | 'ended' | 'unknown';
+/**
+ * The tmux session run `runId` goes on in now. The names it is looked for under are `lastName` (where it was last seen —
+ * the registry may not have written a new run down yet) and every name the registry has seen it under (a resume can
+ * carry it to another one). A name holds it when the tmux session under it is that run (`runOfTmuxSession`), so a name
+ * a new run took over does not count. tmux is asked for its names once and for each candidate once.
+ *
+ * "Ended" only when tmux answered for every candidate: a failure to ask is `unknown`, which a caller waits out rather
+ * than reporting the run as over. So is a run the registry has no record of within `UNRECORDED_RUN_GRACE_MS` of
+ * `boundAt` (when the caller tied itself to the run): the sweep may not have written it down yet, and it may have gone
+ * on under a name nobody knows. Later, no record means the record expired or was evicted — the run is over — unless
+ * the registry file would not read, which says nothing either way.
+ */
+export declare const liveSessionOfRun: (runId: string, lastName: string, tmux: TmuxRuns, now?: number, boundAt?: number) => RunWhereabouts;
 /**
  * Make this process a reader of the registry: `rememberSessions` writes nothing from here on. For the
  * CLI commands that look at the sweep (`hwip agent list|read`) — the file is the listener's resume

package/dist/session-registry.js

@@ -16,7 +16,7 @@
  * another program.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sessionDirectoryExists = exports.knownSessionsPath = exports.isKnownSession = exports.forgetEnded = exports.forgetSession = exports.rememberSessions = exports.keepRegistryUntouched = exports.runOfTmuxSession = exports.continuedRunId = exports.MAX_TMUX_RUNS_PER_RUN = exports.recallRun = exports.recallSession = exports.knownSessions = exports.runKey = exports.KNOWN_SESSION_TTL_MS = exports.MAX_RUNS_PER_NAME = exports.MAX_KNOWN_SESSIONS = void 0;
+exports.sessionDirectoryExists = exports.knownSessionsPath = exports.isKnownSession = exports.forgetEnded = exports.forgetSession = exports.rememberSessions = exports.keepRegistryUntouched = exports.liveSessionOfRun = exports.UNRECORDED_RUN_GRACE_MS = exports.runOfTmuxSession = exports.continuedRunId = exports.MAX_TMUX_RUNS_PER_RUN = exports.recallRun = exports.recallSession = exports.knownSessions = exports.registryUnreadable = exports.runKey = exports.KNOWN_SESSION_TTL_MS = exports.MAX_RUNS_PER_NAME = exports.MAX_KNOWN_SESSIONS = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const turn_ring_js_1 = require("./turn-ring.js");
@@ -99,6 +99,19 @@ const writeAll = (entries) => {
  */
 const runKey = (name, agentKind, runId) => `${name}\u0000${agentKind}\u0000${runId ?? ''}`;
 exports.runKey = runKey;
+/**
+ * The registry file is there but would not read as a list: what `knownSessions` returns then is not all there is
+ * (it reads as empty). No file yet is not unreadable.
+ */
+const registryUnreadable = () => {
+    try {
+        return !Array.isArray(JSON.parse((0, fs_1.readFileSync)(registryPath(), 'utf-8')));
+    }
+    catch (e) {
+        return !(e instanceof Error && 'code' in e && e.code === 'ENOENT');
+    }
+};
+exports.registryUnreadable = registryUnreadable;
 /** Sessions this machine has seen, newest first, expired ones dropped. */
 const knownSessions = (now = Date.now()) => readAll()
     .filter((e) => now - Date.parse(e.lastSeenAt) < exports.KNOWN_SESSION_TTL_MS)
@@ -158,9 +171,45 @@ const continuedRunId = (entries, name, agentKind, tmuxRunId, conversationId) =>
     return earlier?.runId ?? tmuxRunId;
 };
 exports.continuedRunId = continuedRunId;
-/** The run going on in tmux session `tmuxRunId` of `name`: the one it was joined to, else its own. */
-const runOfTmuxSession = (name, tmuxRunId, now = Date.now()) => (0, exports.knownSessions)(now).find((e) => e.name === name && e.tmuxRunIds?.includes(tmuxRunId))?.runId ?? tmuxRunId;
+/** The run going on in tmux session `tmuxRunId` of `name`: the one it was joined to, else its own. `known` is the registry as read. */
+const runOfTmuxSession = (name, tmuxRunId, now = Date.now(), known = (0, exports.knownSessions)(now)) => known.find((e) => e.name === name && e.tmuxRunIds?.includes(tmuxRunId))?.runId ?? tmuxRunId;
 exports.runOfTmuxSession = runOfTmuxSession;
+/** How long after a schedule is tied to a run the registry may still be without a record of it (the listener's sweep writes it). */
+exports.UNRECORDED_RUN_GRACE_MS = 10 * 60_000;
+/**
+ * The tmux session run `runId` goes on in now. The names it is looked for under are `lastName` (where it was last seen —
+ * the registry may not have written a new run down yet) and every name the registry has seen it under (a resume can
+ * carry it to another one). A name holds it when the tmux session under it is that run (`runOfTmuxSession`), so a name
+ * a new run took over does not count. tmux is asked for its names once and for each candidate once.
+ *
+ * "Ended" only when tmux answered for every candidate: a failure to ask is `unknown`, which a caller waits out rather
+ * than reporting the run as over. So is a run the registry has no record of within `UNRECORDED_RUN_GRACE_MS` of
+ * `boundAt` (when the caller tied itself to the run): the sweep may not have written it down yet, and it may have gone
+ * on under a name nobody knows. Later, no record means the record expired or was evicted — the run is over — unless
+ * the registry file would not read, which says nothing either way.
+ */
+const liveSessionOfRun = (runId, lastName, tmux, now = Date.now(), boundAt = now) => {
+    const names = tmux.names();
+    if (names === null)
+        return 'unknown';
+    const running = new Set(names);
+    const known = (0, exports.knownSessions)(now);
+    const recorded = known.filter((e) => e.runId === runId);
+    const candidates = [...new Set([lastName, ...recorded.map((e) => e.name)])];
+    let unsure = false;
+    for (const name of candidates) {
+        if (!running.has(name))
+            continue;
+        const tmuxRunId = tmux.runIdOf(name);
+        if (tmuxRunId === undefined)
+            unsure = true;
+        else if (tmuxRunId !== null && (0, exports.runOfTmuxSession)(name, tmuxRunId, now, known) === runId)
+            return { name };
+    }
+    const noRecord = recorded.length === 0 && (now - boundAt < exports.UNRECORDED_RUN_GRACE_MS || (0, exports.registryUnreadable)());
+    return unsure || noRecord ? 'unknown' : 'ended';
+};
+exports.liveSessionOfRun = liveSessionOfRun;
 let readOnly = false;
 /**
  * Make this process a reader of the registry: `rememberSessions` writes nothing from here on. For the

package/dist/templates.d.ts

@@ -16,7 +16,16 @@ export declare const CLINE_RULE: string;
 export declare const AIDER_RULE: string;
 /** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION), so NORMAL-only core. */
 export declare const PI_RULE: string;
-/** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
+/**
+ * OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook.
+ *
+ * No REMOTE_ENTRY_NO_HOOK, unlike the other hook-less agents: its after-work
+ * ask landed on the phone while the user sat at the terminal (2026-10-29,
+ * OpenCode 2.1.3), and the 2.x plugin API (event stream only) has no per-turn
+ * hook to tell the two apart. So a NORMAL session owes no ask, and REMOTE
+ * starts only from an ask the agent chose to send. Full core, because no hook
+ * delivers the REMOTE sections on entry.
+ */
 export declare const OPENCODE_RULE: string;
 export declare const CURSOR_HOOKS: {
     version: number;

package/dist/templates.js

@@ -21,7 +21,8 @@
 // hook note (a phone message) or by a `hwip_ask` answer. Only Gemini, Codex
 // and Pi have that hook (remoteHookCmd below). Every other agent's only door is the
 // ask itself — so for them the NORMAL branch must still send one after real
-// work, or the phone loop can never begin. That is REMOTE_ENTRY_NO_HOOK.
+// work, or the phone loop can never begin. That is REMOTE_ENTRY_NO_HOOK
+// (OpenCode excepted — OPENCODE_RULE says why).
 //
 // The same axis decides how much of the core the static rule file carries.
 // That file is read on every turn, and a session is NORMAL nearly all of the
@@ -125,7 +126,7 @@ refactor, multi-file changes) call hwip_notify. Skip it for trivial
 operations (file reads, simple searches). Set priority "high" for
 errors/blockers.`;
 // REMOTE-entry preamble — agents with NO prompt-submit hook (Cursor, Windsurf,
-// Copilot, Cline, Aider, OpenCode). The shared core scopes Rules 1/2/8/9 to REMOTE
+// Copilot, Cline, Aider; OpenCode opts out, see OPENCODE_RULE). The shared core scopes Rules 1/2/8/9 to REMOTE
 // and tells a NORMAL session it owes no `hwip_ask`. That is right where a
 // hook can announce the phone message that starts REMOTE; here nothing can,
 // and the only remaining entry is a `hwip_ask` answer reporting REMOTE.
@@ -266,10 +267,18 @@ exports.PI_RULE = buildRule({
     pushSignal: PI_PUSH_SIGNAL,
     core: PROMPT_HOOK_CORE,
 });
-/** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
+/**
+ * OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook.
+ *
+ * No REMOTE_ENTRY_NO_HOOK, unlike the other hook-less agents: its after-work
+ * ask landed on the phone while the user sat at the terminal (2026-10-29,
+ * OpenCode 2.1.3), and the 2.x plugin API (event stream only) has no per-turn
+ * hook to tell the two apart. So a NORMAL session owes no ask, and REMOTE
+ * starts only from an ask the agent chose to send. Full core, because no hook
+ * delivers the REMOTE sections on entry.
+ */
 exports.OPENCODE_RULE = buildRule({
     notify: HOOK_DRIVEN_NOTIFY,
-    remoteEntry: REMOTE_ENTRY_NO_HOOK,
     core: hwip_core_generated_js_1.HWIP_CORE_HOOK_DRIVEN,
 });
 // ── Hook configs ─────────────────────────────────────────────────

package/dist/tmux-liveness.d.ts

@@ -1,4 +1,4 @@
-import type { SessionLiveness } from './session-registry.js';
+import { type SessionLiveness, type TmuxRuns } from './session-registry.js';
 /**
  * Every session name the tmux server currently holds, or null when there was no
  * server to ask — the binary is missing, or nothing answers on the socket this
@@ -18,6 +18,10 @@ export declare const liveSessionNames: () => string[] | null;
  * must refuse on that, as it refuses on `unknown` liveness.
  */
 export declare const liveRunIdOf: (name: string) => string | null | undefined;
+/** What `liveSessionOfRun` (session-registry.ts) asks tmux. */
+export declare const liveTmuxRuns: TmuxRuns;
+/** The run going on under `name` now (`runOfTmuxSession`): null when the name is not running, undefined when no tmux answered. */
+export declare const liveRunOf: (name: string) => string | null | undefined;
 /**
  * The three-state answer, for callers that destroy something on "ended".
  *

package/dist/tmux-liveness.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sessionExists = exports.sessionLiveness = exports.liveRunIdOf = exports.liveSessionNames = void 0;
+exports.sessionExists = exports.sessionLiveness = exports.liveRunOf = exports.liveTmuxRuns = exports.liveRunIdOf = exports.liveSessionNames = void 0;
 const child_process_1 = require("child_process");
+const session_registry_js_1 = require("./session-registry.js");
 const tmux_pane_js_1 = require("./tmux-pane.js");
 const tmux_socket_js_1 = require("./tmux-socket.js");
 /**
@@ -48,6 +49,14 @@ const liveRunIdOf = (name) => {
     return null;
 };
 exports.liveRunIdOf = liveRunIdOf;
+/** What `liveSessionOfRun` (session-registry.ts) asks tmux. */
+exports.liveTmuxRuns = { names: exports.liveSessionNames, runIdOf: exports.liveRunIdOf };
+/** The run going on under `name` now (`runOfTmuxSession`): null when the name is not running, undefined when no tmux answered. */
+const liveRunOf = (name) => {
+    const tmuxRun = (0, exports.liveRunIdOf)(name);
+    return typeof tmuxRun === 'string' ? (0, session_registry_js_1.runOfTmuxSession)(name, tmuxRun) : tmuxRun;
+};
+exports.liveRunOf = liveRunOf;
 /**
  * The three-state answer, for callers that destroy something on "ended".
  *

package/dist/turn-recorder-wire.js

@@ -98,7 +98,7 @@ const createChunkUploader = (opts) => {
         try {
             res = await (0, api_js_1.apiFetch)(fetchFn, (0, api_js_1.apiUrl)(opts.baseUrl, `/sessions/${encodeURIComponent(sessionKey)}/turns`), opts.apiKey, UPLOAD_TIMEOUT_MS, {
                 method: 'POST',
-                body: JSON.stringify({ seq: chunk.seq, firstAt: chunk.firstAt, lastAt: chunk.lastAt, ...(chunk.runId ? { runId: chunk.runId } : {}), sealed: chunk.sealed }),
+                body: JSON.stringify({ seq: chunk.seq, firstAt: chunk.firstAt, lastAt: chunk.lastAt, runId: chunk.runId, sealed: chunk.sealed }),
             });
         }
         catch (err) {

package/dist/turn-recorder.d.ts

@@ -98,8 +98,8 @@ export interface OutboxChunk {
     seq: number;
     firstAt: string;
     lastAt: string;
-    /** The run the events were recorded in. Absent from chunks made before runs were recorded. */
-    runId?: string;
+    /** The run the events were recorded in: the server takes no chunk without one. */
+    runId: string;
     sealed: SealedChunk;
 }
 export type UploadOutcome = 

package/dist/turn-recorder.js

@@ -90,7 +90,7 @@ const isOutboxChunk = (c) => {
     const o = c;
     const s = o.sealed;
     return (Number.isSafeInteger(o.seq) && typeof o.firstAt === 'string' && typeof o.lastAt === 'string' &&
-        !!s && typeof s.body === 'string' && typeof s.senderPublicKey === 'string' &&
+        typeof o.runId === 'string' && !!o.runId && !!s && typeof s.body === 'string' && typeof s.senderPublicKey === 'string' &&
         !!s.deviceKeyMap && typeof s.deviceKeyMap === 'object');
 };
 /** What is on disk, or null when it is missing or not ours (a bad file is a fresh start, never a crash). */
@@ -273,13 +273,21 @@ const createTurnRecorder = (deps) => {
         const chunks = [];
         const runId = runOf(live, live.tailPath);
         let seq = base.seq;
+        // No run to name (a session name that ended, its file still written to): the server takes no such chunk,
+        // so what was read is passed over rather than sealed and sent to be refused.
+        if (!runId && !live.noRunWarned) {
+            live.noRunWarned = true;
+            deps.log(`⧉ turn-recorder ${live.name}: no run to tag its chunks with — what it writes is not recorded`);
+        }
         try {
             for (const page of pages) {
+                if (!runId)
+                    break;
                 seq += 1;
                 const firstAt = eventAt(page, 'first', fallbackAt);
                 const lastAt = eventAt(page, 'last', fallbackAt);
                 const sealed = await deps.seal(JSON.stringify({ sessionKey: live.sessionKey, seq, events: page }), recipients);
-                chunks.push({ seq, firstAt, lastAt, ...(runId ? { runId } : {}), sealed });
+                chunks.push({ seq, firstAt, lastAt, runId, sealed });
             }
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hwip/cli",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Hwip CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",