@hwip/cli 0.1.10 → 0.1.12

package/dist/schedule-remote.js

@@ -10,6 +10,7 @@ const node_path_1 = require("node:path");
 const schedule_js_1 = require("./schedule.js");
 const schedule_ready_js_1 = require("./schedule-ready.js");
 const session_registry_js_1 = require("./session-registry.js");
+const tmux_liveness_js_1 = require("./tmux-liveness.js");
 const wrapper_js_1 = require("./wrapper.js");
 /** The longest prompt the list carries; the full text is in the file on this machine. */
 exports.LIST_PROMPT_CHARS = 500;
@@ -37,9 +38,33 @@ const isoOrNull = (ms) => {
     const date = new Date(ms);
     return Number.isNaN(date.getTime()) ? null : date.toISOString();
 };
-/** The schedules on this machine for the app, oldest first, prompts cut to `promptChars`. Null when the directory could not be listed or holds more than a machine may: an empty list would then be a lie. */
-const phoneScheduleList = (now, promptChars = exports.LIST_PROMPT_CHARS) => {
+/** tmux as `liveSessionOfRun` asks it, each question answered once: one list answer asks for the names once, and each name once. */
+const askingOnce = (tmux) => {
+    let names;
+    const runs = new Map();
+    return {
+        names: () => (names === undefined ? (names = tmux.names()) : names),
+        runIdOf: (name) => {
+            if (!runs.has(name))
+                runs.set(name, tmux.runIdOf(name));
+            return runs.get(name);
+        },
+    };
+};
+/** What the list says about a session target's run: only `ended` is news (the app shows "session ended"). */
+const targetFields = (schedule, now, tmux) => {
+    if (schedule.target !== 'session' || schedule.runId === undefined)
+        return {};
+    const where = (0, session_registry_js_1.liveSessionOfRun)(schedule.runId, schedule.session, tmux, now, Date.parse(schedule.createdAt));
+    return { target: 'session', runId: schedule.runId, ...(where === 'ended' ? { sessionEnded: true } : {}) };
+};
+/**
+ * The schedules on this machine for the app, oldest first, prompts cut to `promptChars`. Null when the directory could
+ * not be listed or holds more than a machine may: an empty list would then be a lie.
+ */
+const phoneScheduleList = (now, promptChars = exports.LIST_PROMPT_CHARS, tmux = tmux_liveness_js_1.liveTmuxRuns) => {
     const read = (0, schedule_js_1.listSchedules)();
+    const asked = askingOnce(tmux);
     if (read.incomplete)
         return null;
     const state = (0, schedule_js_1.readScheduleState)().schedules;
@@ -57,6 +82,7 @@ const phoneScheduleList = (now, promptChars = exports.LIST_PROMPT_CHARS) => {
             maxRuntimeMin: schedule.maxRuntimeMin,
             nextAt: isoOrNull((0, schedule_js_1.nextOccurrence)(schedule.when, now, (0, schedule_js_1.scheduleAnchor)(schedule))),
             ...(last && lastAt ? { last: { outcome: last.outcome, at: lastAt } } : {}),
+            ...targetFields(schedule, now, asked),
         };
     });
     return { schedules, unreadable: read.unreadable };
@@ -67,9 +93,10 @@ exports.phoneScheduleList = phoneScheduleList;
  * cannot hand an older sealed list back as the answer to a newer request. Prompts are cut shorter, step by
  * step, until the answer fits a frame; it is an error only when even the list without prompts does not.
  */
-const scheduleAnswer = (now, requestId, at) => {
+const scheduleAnswer = (now, requestId, at, tmux = tmux_liveness_js_1.liveTmuxRuns) => {
+    const once = askingOnce(tmux);
     for (const promptChars of PROMPT_CHARS_STEPS) {
-        const listing = (0, exports.phoneScheduleList)(now, promptChars);
+        const listing = (0, exports.phoneScheduleList)(now, promptChars, once);
         if (!listing)
             return { ok: false, error: 'read_failed' };
         const { schedules, unreadable } = listing;
@@ -85,10 +112,12 @@ exports.livePhoneScheduleDeps = {
     recall: (session, agentKind) => (agentKind === undefined ? (0, session_registry_js_1.recallSession)(session) : (0, session_registry_js_1.recallRun)(session, agentKind)),
     directoryExists: session_registry_js_1.sessionDirectoryExists,
     canPrompt: schedule_ready_js_1.canPromptKind,
+    currentRun: tmux_liveness_js_1.liveRunOf,
+    recallRunOf: (session, runId, now) => (0, session_registry_js_1.recallSession)(session, now, runId) ?? ((0, session_registry_js_1.registryUnreadable)() ? 'unreadable' : null),
 };
 const refuse = (reason, why) => ({ ok: false, reason, why });
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const CREATE_KEYS = new Set(['op', 'when', 'prompt', 'agentKind', 'maxRuntimeMin']);
+const CREATE_KEYS = new Set(['op', 'when', 'prompt', 'agentKind', 'maxRuntimeMin', 'target']);
 /** Stands in for the run time while the rest of a request is checked; the shortest `validateSchedule` takes. */
 const SHORTEST_RUN_MIN = 5;
 /** The fields every schedule made from a phone request has, whatever the request says: all but `id` come from this machine's record. */
@@ -102,11 +131,50 @@ const fromRecord = (entry, id, now) => ({
     label: `sched-${id}`,
     session: `${(0, wrapper_js_1.tmuxSessionName)((0, wrapper_js_1.safeBasename)(entry.cwd))}-sched-${id}`,
 });
+/**
+ * A create with `target: 'session'`: the schedule types into the addressed session instead of starting one. The run is
+ * the one the session holds now — this machine's word, not the phone's — and the agent and directory are that run's
+ * record. It has no runtime cap: a run time in the request (the apps always send one) is ignored.
+ */
+const createIntoSession = (request, session, deps) => {
+    const { when, prompt, agentKind } = request;
+    if (agentKind !== undefined)
+        return refuse('schedule_invalid', 'a create into a session takes the agent the session runs');
+    const runId = deps.currentRun(session);
+    if (runId === undefined)
+        return refuse('schedule_failed', 'tmux did not give the run of that session');
+    if (runId === null)
+        return refuse('unknown_session', 'the session is not running');
+    const now = deps.now();
+    const entry = deps.recallRunOf(session, runId, now);
+    if (entry === 'unreadable')
+        return refuse('schedule_failed', 'the record of sessions would not read');
+    if (!entry)
+        return refuse('unknown_session', 'no record of the run that session holds');
+    if (!deps.canPrompt(entry.agentKind))
+        return refuse('schedule_invalid', `${entry.agentKind} cannot take a scheduled prompt`);
+    const checked = (0, schedule_js_1.validateSchedule)({
+        v: 1, id: 'aaaaaa', createdAt: new Date(now).toISOString(), source: 'phone', agentKind: entry.agentKind, cwd: entry.cwd,
+        label: 'sched-aaaaaa', session, target: 'session', runId, when, prompt, maxRuntimeMin: SHORTEST_RUN_MIN,
+    });
+    if (!checked.ok)
+        return refuse('schedule_invalid', checked.error);
+    // Kept for the file's shape: a session target's run time bounds nothing.
+    const runtime = (0, schedule_js_1.defaultMaxRuntimeMin)(checked.value.when);
+    const added = (0, schedule_js_1.addSchedule)((id) => ({ ...checked.value, id, label: `sched-${id}`, maxRuntimeMin: runtime }));
+    if (added.ok)
+        return { ok: true };
+    return refuse(added.failure === 'limit' ? 'schedule_limit' : added.failure === 'io' ? 'schedule_failed' : 'schedule_invalid', added.error);
+};
 const create = (request, session, deps) => {
     // Whatever else the request carries — a directory, arguments, a label — is refused, not ignored: it was meant to be used.
     const extra = Object.keys(request).find((k) => !CREATE_KEYS.has(k));
     if (extra !== undefined)
         return refuse('schedule_invalid', `a create carries ${extra}`);
+    if (request.target !== undefined && request.target !== 'session')
+        return refuse('schedule_invalid', "target is 'session' or absent");
+    if (request.target === 'session')
+        return createIntoSession(request, session, deps);
     const { when, prompt, agentKind, maxRuntimeMin } = request;
     if (agentKind !== undefined && typeof agentKind !== 'string')
         return refuse('schedule_invalid', 'agentKind is not text');
@@ -180,7 +248,8 @@ const update = (request, session, deps) => {
         change.when = when;
     if (prompt !== undefined)
         change.prompt = prompt;
-    if (maxRuntimeMin !== undefined)
+    // The apps always send a run time; a session target has none to change, and keeps the one in its file.
+    if (maxRuntimeMin !== undefined && target.target !== 'session')
         change.maxRuntimeMin = maxRuntimeMin;
     const updated = (0, schedule_js_1.updateSchedule)(id, change, deps.now());
     if (updated.ok)
@@ -190,7 +259,7 @@ const update = (request, session, deps) => {
 };
 /**
  * Carry out one change the phone asked for: `{ op: 'create', when, prompt, agentKind?, maxRuntimeMin? }` for the
- * recorded session `session`, `{ op: 'update', id, when?, prompt?, maxRuntimeMin? }` or `{ op: 'remove', id }` for the
+ * recorded session `session` (or `{ op: 'create', target: 'session', when, prompt }` to type into it), `{ op: 'update', id, when?, prompt?, maxRuntimeMin? }` or `{ op: 'remove', id }` for the
  * schedule whose session that is. Nothing here
  * types into a session. `request` is whatever the phone sealed, so every field is checked as it is used.
  */

package/dist/schedule-runner.d.ts

@@ -5,14 +5,25 @@
  *
  * What a tick decides, per schedule: how many due times passed since its cursor, whether the newest is still
  * worth running (`GRACE_MS`; older ones are `missed` and never run late), and whether the session may start.
+ * A `once` schedule that has run (or was missed), and whose session and report are done with, has its file removed.
+ *
+ * A session target (`target: 'session'`) starts nothing: at its time it waits (`delivering`) for the run it is bound to
+ * to be idle with nobody typing at its terminal, and types the prompt in. It never counts as running, has no runtime
+ * cap and is never asked to end — the session is the person's, not the schedule's.
  * The cursor is written before anything is launched, so a listener killed in between skips that run instead of
  * starting it twice.
  */
-import { type Schedule, type ScheduleList, type ScheduleStateFile } from './schedule.js';
+import type { RunWhereabouts } from './session-registry.js';
+import { type RemoveResult, type Schedule, type ScheduleList, type ScheduleStateFile } from './schedule.js';
 /** How often the listener ticks. */
 export declare const TICK_MS = 30000;
 /** A due time older than this when the tick sees it (the machine slept, the listener was down) is missed, not run. */
 export declare const GRACE_MS = 120000;
+/**
+ * The same for a `once` schedule: there is no next time to wait for, and a person who asked for "at 3 pm" still wants
+ * it at 3:20 after the laptop woke up.
+ */
+export declare const ONCE_GRACE_MS: number;
 /** After a launch exits 0, how long before the session has to be there. */
 export declare const START_CHECK_MS = 2000;
 /** A launch that has not exited by then is given up on. */
@@ -30,6 +41,10 @@ export declare const PROMPT_POLL_MS = 5000;
  * the session is idle, and a retry after a failed inject two polls later.
  */
 export declare const PROMPT_WAIT_MS = 90000;
+/** How long a session target's prompt waits for its session to be idle (and its terminal quiet) before it is `session_busy`. */
+export declare const SESSION_WAIT_MS: number;
+/** A terminal attached to the session that had a key pressed this recently is someone typing: the prompt is not typed after their words. */
+export declare const SESSION_QUIET_MS: number;
 /** Scheduled sessions running at once. */
 export declare const MAX_RUNNING = 3;
 export type LaunchResult = {
@@ -71,6 +86,15 @@ export interface ScheduleRunnerDeps {
     endSession: (session: string) => void;
     /** Tells the person (title, body). */
     notify: (title: string, body: string) => Promise<NotifyOutcome>;
+    /** Where the run `runId` (last seen in session `lastName`, tied to at `boundAt`) goes on now (`liveSessionOfRun`). */
+    sessionOfRun: (runId: string, lastName: string, boundAt: number) => RunWhereabouts;
+    /**
+     * When a terminal attached to `session` was last used (ms since the epoch); null when none is attached, undefined
+     * when tmux could not say.
+     */
+    lastClientActivity: (session: string) => number | null | undefined;
+    /** Deletes a schedule's file (`removeSchedule`): a `once` that is done. It may throw when the file cannot be removed. */
+    removeSchedule: (id: string) => RemoveResult;
     /** The wall clock (default `Date.now`); a launch takes seconds, and the schedules after it are judged by the time it ends. */
     clock?: () => number;
 }

package/dist/schedule-runner.js

@@ -6,16 +6,26 @@
  *
  * What a tick decides, per schedule: how many due times passed since its cursor, whether the newest is still
  * worth running (`GRACE_MS`; older ones are `missed` and never run late), and whether the session may start.
+ * A `once` schedule that has run (or was missed), and whose session and report are done with, has its file removed.
+ *
+ * A session target (`target: 'session'`) starts nothing: at its time it waits (`delivering`) for the run it is bound to
+ * to be idle with nobody typing at its terminal, and types the prompt in. It never counts as running, has no runtime
+ * cap and is never asked to end — the session is the person's, not the schedule's.
  * The cursor is written before anything is launched, so a listener killed in between skips that run instead of
  * starting it twice.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createScheduleRunner = exports.launchArgs = exports.notifyFailureOutcome = exports.MAX_RUNNING = exports.PROMPT_WAIT_MS = exports.PROMPT_POLL_MS = exports.PUSH_RETRY_MAX_MS = exports.PUSH_RETRY_MS = exports.LAUNCH_WT_TIMEOUT_MS = exports.LAUNCH_TIMEOUT_MS = exports.START_CHECK_MS = exports.GRACE_MS = exports.TICK_MS = void 0;
+exports.createScheduleRunner = exports.launchArgs = exports.notifyFailureOutcome = exports.MAX_RUNNING = exports.SESSION_QUIET_MS = exports.SESSION_WAIT_MS = exports.PROMPT_WAIT_MS = exports.PROMPT_POLL_MS = exports.PUSH_RETRY_MAX_MS = exports.PUSH_RETRY_MS = exports.LAUNCH_WT_TIMEOUT_MS = exports.LAUNCH_TIMEOUT_MS = exports.START_CHECK_MS = exports.ONCE_GRACE_MS = exports.GRACE_MS = exports.TICK_MS = void 0;
 const schedule_js_1 = require("./schedule.js");
 /** How often the listener ticks. */
 exports.TICK_MS = 30_000;
 /** A due time older than this when the tick sees it (the machine slept, the listener was down) is missed, not run. */
 exports.GRACE_MS = 120_000;
+/**
+ * The same for a `once` schedule: there is no next time to wait for, and a person who asked for "at 3 pm" still wants
+ * it at 3:20 after the laptop woke up.
+ */
+exports.ONCE_GRACE_MS = 30 * 60_000;
 /** After a launch exits 0, how long before the session has to be there. */
 exports.START_CHECK_MS = 2_000;
 /** A launch that has not exited by then is given up on. */
@@ -33,6 +43,10 @@ exports.PROMPT_POLL_MS = 5_000;
  * the session is idle, and a retry after a failed inject two polls later.
  */
 exports.PROMPT_WAIT_MS = 90_000;
+/** How long a session target's prompt waits for its session to be idle (and its terminal quiet) before it is `session_busy`. */
+exports.SESSION_WAIT_MS = 30 * 60_000;
+/** A terminal attached to the session that had a key pressed this recently is someone typing: the prompt is not typed after their words. */
+exports.SESSION_QUIET_MS = 3 * 60_000;
 /** A report that has waited this long for a push that would not go through is dropped, not sent as news. */
 const PENDING_MAX_MS = 24 * 60 * 60 * 1000;
 /** Scheduled sessions running at once. */
@@ -70,6 +84,8 @@ const REASON_TEXT = {
     prompt_undelivered: '할 일 입력 못 함',
     prompt_unsupported: '할 일 입력 불가(이 에이전트는 입력 준비를 판정할 규칙이 없음)',
     capped: '실행 시간 초과',
+    session_busy: '세션이 계속 작업 중이라 건너뜀',
+    session_ended: '세션 종료됨',
 };
 /** The push title for each result: what kind of news it is. A report that mixes kinds gets the general one. */
 const SKIPPED = '예약 건너뜀';
@@ -84,6 +100,8 @@ const TITLE_OF = {
     prompt_undelivered: PROMPT_NOT_TYPED,
     prompt_unsupported: PROMPT_NOT_TYPED,
     capped: '예약 실행 시간 초과',
+    session_busy: SKIPPED,
+    session_ended: '예약 세션 종료됨',
 };
 const MIXED_TITLE = '예약 알림';
 /** Adds `count` of `outcome` to what the person has not been told yet. */
@@ -125,6 +143,50 @@ const createScheduleRunner = (deps) => {
     const launchedBefore = new Map();
     // Sessions already asked to end for their runtime cap, so a state file that cannot be written does not ask again every tick.
     const cappedAsked = new Set();
+    // `once` schedules whose file could not be removed, so the log says it once, not every tick.
+    const unremovable = new Set();
+    /**
+     * Removes the `once` schedules that are done: their time has been dealt with (run, failed or missed), their session is
+     * no longer running and their report has gone out. Until then the schedule stays, so its prompt, its runtime cap and
+     * its push are still looked after. Its cursor is past its time, so one that cannot be removed is never run again.
+     * A cursor can also pass the time without a run judging it (a damaged state file starts from now): that is told as
+     * missed first, never removed in silence.
+     */
+    const removeFinished = (schedules, state, now) => {
+        let changed = false;
+        const live = schedules.filter((schedule) => {
+            const st = state[schedule.id];
+            const passed = schedule.when.kind === 'once' && st.cursor >= Date.parse(schedule.when.at);
+            if (!passed || st.running || st.delivering || st.pending)
+                return true;
+            if (!st.last) {
+                st.last = { outcome: 'missed', at: now };
+                addPending(st, 'missed', 1, now);
+                changed = true;
+                deps.log(`schedule ${schedule.id} (${schedule.label}): its time went by without a record; missed`);
+                return true;
+            }
+            let removed;
+            try {
+                removed = deps.removeSchedule(schedule.id);
+            }
+            catch (e) {
+                removed = e instanceof Error ? e : new Error(String(e));
+            }
+            if (removed instanceof Error || removed === 'invalid') {
+                if (!unremovable.has(schedule.id))
+                    deps.log(`! schedule ${schedule.id} (${schedule.label}): ran once, but could not remove it: ${removed instanceof Error ? removed.message : 'not a schedule id'}`);
+                unremovable.add(schedule.id);
+                return true;
+            }
+            unremovable.delete(schedule.id);
+            delete state[schedule.id];
+            deps.log(`schedule ${schedule.id} (${schedule.label}): ran once, removed`);
+            changed = true;
+            return false;
+        });
+        return { live, changed };
+    };
     const load = (tickNow) => {
         const { schedules, unreadable, incomplete } = deps.listSchedules();
         const file = deps.readState();
@@ -191,13 +253,41 @@ const createScheduleRunner = (deps) => {
             sentReports = [];
             pushing = false;
         }
+        const { live, changed } = removeFinished(schedules, state, tickNow);
+        if (changed)
+            dirty = true;
         const save = () => {
             const saved = deps.writeState({ v: 1, schedules: state });
             if (!saved)
                 deps.log('! schedules: could not write the state file');
             return saved;
         };
-        return { schedules, state, dirty, save };
+        return { schedules: live, state, dirty, save };
+    };
+    /** The end of a session target's time: what became of it, told unless it is the same as the last time (a streak). */
+    const settle = (st, outcome, now) => {
+        delete st.delivering;
+        // As with overlap and busy: a run that is over, or never idle, stays so for every time until someone acts.
+        const repeat = (outcome === 'session_busy' || outcome === 'session_ended') && st.last?.outcome === outcome;
+        st.last = { outcome, at: now };
+        if (outcome !== 'started' && !repeat)
+            addPending(st, outcome, 1, now);
+    };
+    /** A session target's time came: its wait begins, or (when it cannot) what that means. Returns what to log. */
+    const beginDelivery = (schedule, st, now) => {
+        if (!deps.canPrompt(schedule.agentKind)) {
+            settle(st, 'prompt_unsupported', now);
+            return `${schedule.agentKind} has no rule that says idle, so its prompt is not typed`;
+        }
+        // The last time's prompt is still waiting: this one is not queued behind it.
+        if (st.delivering) {
+            const { delivering } = st;
+            settle(st, 'session_busy', now);
+            st.delivering = delivering;
+            return 'session_busy (the last prompt is still waiting)';
+        }
+        st.delivering = { session: schedule.session, since: now };
+        return `waiting for ${schedule.session} to be idle`;
     };
     const run = async (tickNow) => {
         const tickStart = clock();
@@ -212,7 +302,7 @@ const createScheduleRunner = (deps) => {
             const due = (0, schedule_js_1.occurrencesBetween)(schedule.when, st.cursor, now, (0, schedule_js_1.scheduleAnchor)(schedule));
             if (due.count === 0 || due.latest === null)
                 continue;
-            const runs = now - due.latest <= exports.GRACE_MS;
+            const runs = now - due.latest <= (schedule.when.kind === 'once' ? exports.ONCE_GRACE_MS : exports.GRACE_MS);
             const missed = runs ? due.count - 1 : due.count;
             const before = structuredClone(st);
             st.cursor = due.latest;
@@ -221,6 +311,9 @@ const createScheduleRunner = (deps) => {
                 st.last = { outcome: 'missed', at: now };
                 addPending(st, 'missed', missed, now);
             }
+            const intoSession = runs && schedule.target === 'session';
+            // Saved with the cursor: a wait that is on disk is never begun twice, nor lost.
+            const begun = intoSession ? beginDelivery(schedule, st, now) : null;
             if (!save()) {
                 state[schedule.id] = before;
                 continue;
@@ -228,7 +321,9 @@ const createScheduleRunner = (deps) => {
             loaded.dirty = false;
             if (missed > 0)
                 deps.log(`schedule ${schedule.id} (${schedule.label}): missed ${missed} run${missed === 1 ? '' : 's'}`);
-            if (runs)
+            if (begun)
+                deps.log(`schedule ${schedule.id} (${schedule.label}): ${begun}`);
+            if (runs && !intoSession)
                 toStart.push({ schedule, st, before, at: now });
         }
         for (const { schedule, st, before, at: now } of toStart) {
@@ -302,11 +397,95 @@ const createScheduleRunner = (deps) => {
     };
     // Prompts typed whose "done" could not be written (`session@startedAt`); in memory, so only for this listener's life.
     const delivered = new Set();
-    // Whether any running session is still waiting for its prompt: `poll` costs nothing while none is.
+    // Whether any prompt is still waiting (a started session's or a session target's): `poll` costs nothing while none is.
     let watching = true;
-    /** Delivers the prompts of running sessions and ends those past their runtime cap, then saves what changed. */
+    // Why each session target's wait has not typed yet (`<id>@<since>`), for the log and outcome when it runs out. In
+    // memory: after a restart the reason starts over, which only changes the log line.
+    const waitNotes = new Map();
+    /**
+     * Types the prompts of session targets into their runs: when the run is idle and nobody has used a terminal attached
+     * to it for `SESSION_QUIET_MS`. One prompt per session per pass, the earliest due first — the next waits for the
+     * session to be idle again. A run that is over fails the wait; one tmux cannot find right now is waited for.
+     */
+    const deliver = (loaded, now) => {
+        const { schedules, state } = loaded;
+        const typedInto = new Set();
+        const waiting = schedules
+            .filter((schedule) => state[schedule.id].delivering)
+            .sort((a, b) => state[a.id].cursor - state[b.id].cursor || a.id.localeCompare(b.id));
+        for (const schedule of waiting) {
+            const st = state[schedule.id];
+            const delivering = st.delivering;
+            const label = `schedule ${schedule.id} (${schedule.label})`;
+            const deliveredKey = `${schedule.id}@${delivering.since}`;
+            if (delivered.has(deliveredKey)) {
+                delete st.delivering;
+                loaded.dirty = true;
+                continue;
+            }
+            if (schedule.prompt === undefined || schedule.runId === undefined) {
+                // `validateSchedule` gives every session target both; a wait without them has nothing to type.
+                deps.log(`! ${label}: a session target without a prompt or a run; its wait is dropped`);
+                delete st.delivering;
+                loaded.dirty = true;
+                continue;
+            }
+            const note = waitNotes.get(deliveredKey) ?? { reason: 'it was not idle' };
+            waitNotes.set(deliveredKey, note);
+            // Asked before the deadline: a run that ended while its prompt waited is over, not busy.
+            const where = deps.sessionOfRun(schedule.runId, delivering.session, Date.parse(schedule.createdAt));
+            if (where === 'ended') {
+                waitNotes.delete(deliveredKey);
+                settle(st, 'session_ended', now);
+                deps.log(`${label}: the session it types into has ended`);
+                saveNow(loaded);
+                continue;
+            }
+            if (now - delivering.since > exports.SESSION_WAIT_MS) {
+                waitNotes.delete(deliveredKey);
+                settle(st, note.injectFailed ? 'prompt_undelivered' : 'session_busy', now);
+                deps.log(`${label}: not typed within ${exports.SESSION_WAIT_MS / 60_000} min (${note.reason}); skipped`);
+                saveNow(loaded);
+                continue;
+            }
+            if (where === 'unknown') {
+                note.reason = 'tmux could not say where the run is';
+                continue;
+            }
+            if (where.name !== delivering.session) {
+                delivering.session = where.name;
+                loaded.dirty = true;
+            }
+            if (typedInto.has(where.name))
+                continue;
+            const used = deps.lastClientActivity(where.name);
+            if (used === undefined || (used !== null && now - used < exports.SESSION_QUIET_MS)) {
+                note.reason = used === undefined ? 'tmux could not say who uses its terminal' : 'someone was typing at its terminal';
+                continue;
+            }
+            if (!deps.ready(where.name, schedule.agentKind)) {
+                note.reason = 'it was not idle';
+                continue;
+            }
+            if (!deps.inject(where.name, schedule.prompt)) {
+                // Rate limit, no pane …: the next poll tries again, and the wait ends as undelivered, not busy.
+                note.reason = 'the prompt would not go in';
+                note.injectFailed = true;
+                continue;
+            }
+            waitNotes.delete(deliveredKey);
+            typedInto.add(where.name);
+            settle(st, 'started', now);
+            deps.log(`${label}: prompt typed into ${where.name}`);
+            // On disk right away, as for a started session's prompt: a restart must not type it again.
+            if (!saveNow(loaded))
+                delivered.add(deliveredKey);
+        }
+    };
+    /** Delivers the prompts of running sessions and session targets, ends sessions past their runtime cap, then saves what changed. */
     const supervise = (loaded, now) => {
         const { schedules, state } = loaded;
+        deliver(loaded, now);
         for (const schedule of schedules) {
             const st = state[schedule.id];
             const running = st.running;
@@ -370,7 +549,7 @@ const createScheduleRunner = (deps) => {
                 saveNow(loaded);
             }
         }
-        watching = Object.values(state).some((st) => st.running?.promptPending);
+        watching = Object.values(state).some((st) => st.running?.promptPending || st.delivering);
         if (loaded.dirty)
             loaded.save();
     };

package/dist/schedule.d.ts

@@ -2,8 +2,8 @@
  * 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.
@@ -15,6 +15,11 @@ export type ScheduleWhen = {
 } | {
     kind: 'every';
     minutes: number;
+}
+/** Runs one time, at `at` (an ISO 8601 instant), and is removed after (`schedule-runner.ts`). */
+ | {
+    kind: 'once';
+    at: string;
 };
 export interface Schedule {
     v: 1;
@@ -29,8 +34,18 @@ export interface Schedule {
     cwd: string;
     /** Passed to `hwip <agent> --label`; the default is `sched-<id>`. */
     label: string;
-    /** The tmux session the launch will create, worked out when the schedule is made. */
+    /**
+     * The tmux session the launch will create, worked out when the schedule is made. For a `target: 'session'` schedule,
+     * the session the run was in when the schedule was made: where the runner looks for it first.
+     */
     session: string;
+    /**
+     * `session`: no session is started; at its time the prompt is typed into the run `runId` is, wherever it goes on
+     * (`liveSessionOfRun`). Absent: a new session is started (`hwip <agent> --detach`). Fixed once made.
+     */
+    target?: 'session';
+    /** The run (hwip docs/session-runs.md) a `target: 'session'` schedule types into, and only with it. */
+    runId?: string;
     /** `--wt <branch>`. From the command line only. */
     wt?: string;
     /** Arguments after `--`. From the command line only. */
@@ -39,6 +54,12 @@ export interface Schedule {
     when: ScheduleWhen;
     maxRuntimeMin: number;
 }
+/**
+ * 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.
+ */
+export declare const SCHEDULE_SESSION_CAPABILITY = "schedule-session-v1";
 export type Checked<T> = {
     ok: true;
     value: T;
@@ -54,11 +75,12 @@ export declare const ALL_DAYS: readonly number[];
 export declare const WEEKDAYS: readonly number[];
 /** `<N>m` or `<N>h` as minutes; `example` is what the error shows for a value that is neither. */
 export declare const parseDuration: (raw: string, flag: string, example: string) => Checked<number>;
-/** `--at HH:MM [--days …]` or `--every <N>m|<N>h`, not both and not neither. */
+/** `--at HH:MM [--days …]`, `--on YYYY-MM-DD --at HH:MM` or `--every <N>m|<N>h`, one of them and not neither. */
 export declare const parseWhen: (input: {
     at?: string;
     days?: string;
     every?: string;
+    on?: string;
 }) => Checked<ScheduleWhen>;
 export interface Occurrences {
     count: number;
@@ -75,7 +97,7 @@ export interface Occurrences {
  * the clock repeats (fall) happens once, the first time round.
  */
 export declare const occurrencesBetween: (when: ScheduleWhen, after: number, until: number, anchor: number) => Occurrences;
-/** 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). */
 export declare const nextOccurrence: (when: ScheduleWhen, after: number, anchor: number) => number | null;
 export declare const isScheduleId: (value: unknown) => value is string;
 /**
@@ -134,12 +156,14 @@ export type UpdateResult = {
  * missed. A change of the prompt or the run time only keeps the count where it was — an hourly run stays on its hour.
  */
 export declare const updateSchedule: (id: string, change: UncheckedScheduleChange, now: number) => UpdateResult;
+/** Why `when` cannot be given to a schedule at `now`: a `once` whose time has passed would never run. Null when it can. */
+export declare const pastWhen: (when: ScheduleWhen, now: number) => string | null;
 /** The time a schedule's runs are counted from: its last edit, else its creation. */
 export declare const scheduleAnchor: (schedule: Schedule) => number;
 /** `invalid` means the id could not name a schedule file; nothing was touched. */
 export type RemoveResult = 'removed' | 'missing' | 'invalid';
 export declare const removeSchedule: (id: string) => RemoveResult;
-declare const SCHEDULE_OUTCOMES: readonly ["started", "missed", "overlap", "busy", "start_failed", "missing_directory", "unknown_agent", "prompt_undelivered", "prompt_unsupported", "capped"];
+declare const SCHEDULE_OUTCOMES: readonly ["started", "missed", "overlap", "busy", "start_failed", "missing_directory", "unknown_agent", "prompt_undelivered", "prompt_unsupported", "capped", "session_busy", "session_ended"];
 export type ScheduleOutcome = (typeof SCHEDULE_OUTCOMES)[number];
 /** Per schedule, in `schedule-state.json`. Only the listener writes it (`schedule-runner.ts`); `hwip schedule list` reads it. */
 export interface ScheduleRunState {
@@ -152,6 +176,14 @@ export interface ScheduleRunState {
         promptPending: boolean;
         capped?: true;
     };
+    /**
+     * A session target whose time came and whose prompt waits for its session to be idle. `session` is where the run was
+     * last seen; `since` is when the wait began, and the wait is given up on 30 minutes after it (`schedule-runner.ts`).
+     */
+    delivering?: {
+        session: string;
+        since: number;
+    };
     last?: {
         outcome: ScheduleOutcome;
         at: number;