@hwip/cli 0.1.9 → 0.1.11

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/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/wrapper.d.ts

@@ -32,6 +32,8 @@ export declare const herdrSessionArgs: (session: string, env?: NodeJS.ProcessEnv
  * an older tmux gets none, as before.
  */
 export declare const herdrEnvArgs: (agentKind: string | undefined, env: NodeJS.ProcessEnv, tmuxVersion: string) => string[];
+export declare const agentLaunchEnv: (agentKind: string | undefined, env: NodeJS.ProcessEnv) => Record<string, string>;
+export declare const agentLaunchArgs: (agentKind: string | undefined, extra: string[]) => string[];
 /** `tmux -V`, read once per process; empty when tmux does not answer. */
 export declare const installedTmuxVersion: () => string;
 /**
@@ -91,6 +93,8 @@ export interface SpawnTarget {
     args: string[];
     /** The tmux session name for the two tmux kinds — carried, not re-read off argv. */
     session?: string;
+    /** Variables the agent runs with on top of this process's env (`direct`); the tmux kinds carry them as `-e`. */
+    env?: Record<string, string>;
 }
 /**
  * `hwip <agent> --detach --label <x> --wt <name> …` — the wrapper-owned flags. They

package/dist/wrapper.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.targetForAgent = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.familyNames = exports.firstFreeSession = exports.tmuxSessionName = exports.installedTmuxVersion = exports.herdrEnvArgs = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
+exports.handleShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.targetForAgent = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.familyNames = exports.firstFreeSession = exports.tmuxSessionName = exports.installedTmuxVersion = exports.agentLaunchArgs = exports.agentLaunchEnv = exports.herdrEnvArgs = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
 /**
  * `hwip cc` / `hwip codex` / `hwip gemini` — spawn an agent inside a named
  * tmux session so the resident listener (`hwip listener`) can address it
@@ -106,6 +106,36 @@ const herdrEnvArgs = (agentKind, env, tmuxVersion) => {
     return config_js_1.HERDR_ENV_VARS.flatMap((name) => ['-e', `${name}=${native ? env[name] ?? '' : ''}`]);
 };
 exports.herdrEnvArgs = herdrEnvArgs;
+/**
+ * Env that keeps an agent's transcript in tmux scrollback, by kind. A
+ * full-screen renderer draws on the alternate screen, where tmux keeps no
+ * history, so the phone cannot page back. Claude Code's fullscreen renderer
+ * is a user setting (`/tui fullscreen`); this forces the classic one. A value
+ * the launching shell already sets wins.
+ */
+const AGENT_LAUNCH_ENV = {
+    claude: { CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN: '1' },
+};
+const agentLaunchEnv = (agentKind, env) => Object.fromEntries(Object.entries(AGENT_LAUNCH_ENV[agentKind ?? ''] ?? {}).map(([name, value]) => [name, env[name] ?? value]));
+exports.agentLaunchEnv = agentLaunchEnv;
+/**
+ * Leading flags with the same aim, by kind, for an agent whose renderer is a
+ * flag: pi defaults to `--tui-mode fullscreen`. Left off when the caller
+ * passes the flag itself.
+ */
+const AGENT_LAUNCH_ARGS = {
+    pi: ['--tui-mode', 'regular'],
+};
+const agentLaunchArgs = (agentKind, extra) => {
+    const lead = AGENT_LAUNCH_ARGS[agentKind ?? ''] ?? [];
+    const flag = lead[0];
+    if (flag === undefined || extra.some((a) => a === flag || a.startsWith(`${flag}=`)))
+        return extra;
+    return [...lead, ...extra];
+};
+exports.agentLaunchArgs = agentLaunchArgs;
+/** `new-session -e` flags for `agentLaunchEnv`; none before tmux 3.2, as for herdr. */
+const launchEnvArgs = (launchEnv, tmuxVersion) => sessionEnvSupported(tmuxVersion) ? Object.entries(launchEnv).flatMap(([name, value]) => ['-e', `${name}=${value}`]) : [];
 /** `tmux -V` says 3.2 or later (`new-session -e`); a development build (`next-3.7`, `master`) is newer. */
 const sessionEnvSupported = (version) => {
     if (/\b(master|next-)/.test(version))
@@ -310,8 +340,10 @@ const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     // is exactly where it runs from.
     // A label asks for a tmux session by name; running in the current pane
     // would drop that silently, so a label is the other exception.
+    const launchEnv = (0, exports.agentLaunchEnv)(agentKind, process.env);
+    extra = (0, exports.agentLaunchArgs)(agentKind, extra);
     if (process.env.TMUX && !opts.detach && !opts.label) {
-        return { kind: 'direct', cmd: agent, args: extra };
+        return { kind: 'direct', cmd: agent, args: extra, ...(Object.keys(launchEnv).length ? { env: launchEnv } : {}) };
     }
     const projectDir = opts.projectDir ?? (0, exports.detectProjectDir)();
     const base = (0, exports.tmuxSessionName)((0, exports.safeBasename)(projectDir));
@@ -342,11 +374,13 @@ const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     if (opts.detach) {
         // Attached to no herdr pane: blank, whatever pane this command was typed in.
         const herdrEnv = (0, exports.herdrEnvArgs)(agentKind, {}, (0, exports.installedTmuxVersion)());
-        return { kind: 'tmux-detached', cmd: 'tmux', args: ['new', '-d', '-s', session, '-c', projectDir, ...herdrEnv, shellCmd, ...sidecar], session };
+        const agentEnv = launchEnvArgs(launchEnv, (0, exports.installedTmuxVersion)());
+        return { kind: 'tmux-detached', cmd: 'tmux', args: ['new', '-d', '-s', session, '-c', projectDir, ...herdrEnv, ...agentEnv, shellCmd, ...sidecar], session };
     }
     // `tmux new -A`: attach if the named session exists, else create it. `-e` applies only when it creates.
     const herdrEnv = (0, exports.herdrEnvArgs)(agentKind, process.env, (0, exports.installedTmuxVersion)());
-    return { kind: 'tmux-new', cmd: 'tmux', args: ['new', '-A', '-s', session, ...herdrEnv, shellCmd, ...sidecar, ...(0, exports.herdrSessionArgs)(session)], session };
+    const agentEnv = launchEnvArgs(launchEnv, (0, exports.installedTmuxVersion)());
+    return { kind: 'tmux-new', cmd: 'tmux', args: ['new', '-A', '-s', session, ...herdrEnv, ...agentEnv, shellCmd, ...sidecar, ...(0, exports.herdrSessionArgs)(session)], session };
 };
 exports.targetForAgent = targetForAgent;
 // ── Background listener auto-start ────────────────────────────────────
@@ -561,7 +595,7 @@ const handleAgentSession = async (agent, extra = [], opts = {}, deps = {}) => {
     // spawned from here would inherit the worktree as its cwd, and it is the one that later removes the directory.
     if (opts.worktree && opts.projectDir)
         process.chdir(opts.projectDir);
-    const { kind, cmd, args, session } = (0, exports.targetForAgent)(agent.binary, extra, agent.kind, opts);
+    const { kind, cmd, args, session, env } = (0, exports.targetForAgent)(agent.binary, extra, agent.kind, opts);
     const note = kind === 'direct' ? (0, exports.inPaneNote)(agent.subcommands[0], currentTmuxSession()) : undefined;
     if (note)
         console.error(note);
@@ -575,7 +609,7 @@ const handleAgentSession = async (agent, extra = [], opts = {}, deps = {}) => {
             return 1;
         }
     }
-    return (deps.launch ?? launchTarget)({ kind, cmd, args, session }, agent.binary);
+    return (deps.launch ?? launchTarget)({ kind, cmd, args, session, env }, agent.binary);
 };
 exports.handleAgentSession = handleAgentSession;
 /**
@@ -583,7 +617,8 @@ exports.handleAgentSession = handleAgentSession;
  * hands the terminal over (execve where it can, a waited child where not) and
  * forwards the exit code. `what` names the program in the detached message.
  */
-const launchTarget = async ({ kind, cmd, args, session }, what) => {
+const launchTarget = async ({ kind, cmd, args, session, env: agentEnv }, what) => {
+    const env = agentEnv ? { ...process.env, ...agentEnv } : process.env;
     if (kind === 'tmux-detached' && session) {
         const r = (0, child_process_1.spawnSync)(cmd, args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
         if (r.error || r.status !== 0) {
@@ -601,7 +636,7 @@ const launchTarget = async ({ kind, cmd, args, session }, what) => {
     // exit code that execve gives us for free by being the same process.
     const handOff = (0, exports.handOffExec)({
         execve: process.execve,
-        env: process.env,
+        env,
         kind,
         stdinTTY: process.stdin.isTTY,
         stdoutTTY: process.stdout.isTTY,
@@ -621,7 +656,7 @@ const launchTarget = async ({ kind, cmd, args, session }, what) => {
     }
     return new Promise((resolve) => {
         const start = Date.now();
-        const child = (0, child_process_1.spawn)(cmd, args, { stdio: 'inherit' });
+        const child = (0, child_process_1.spawn)(cmd, args, { stdio: 'inherit', env });
         child.on('exit', (code) => {
             const dur = Date.now() - start;
             // Short-lived non-zero exits are the symptom of "ran from a

package/package.json

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