looply-cli 0.0.0-stage → 0.3.0

package/dist/notify-cadence.d.ts

@@ -0,0 +1,55 @@
+import type { RoundOutcome, RunTotals } from '@looply/core';
+/**
+ * Notify cadence: when the run speaks, given `notify.every_min`.
+ *
+ * The round runner reports *that* things happened; this class decides *whether
+ * the phone hears about it*. Keeping the cadence out of the runner means the
+ * every_min rules are testable with no git, no queue and no rounds — and the
+ * runner stays ignorant of clocks-between-messages entirely.
+ *
+ * The one absolute rule (DESIGN §12 case 35): `every_min: 0` means silence.
+ * Not "fewer messages" — none, including the start and finish lines. A user who
+ * turned reporting off and still gets a 3am "looply started" SMS learns that
+ * the off switch is decorative, and stops trusting every other rail.
+ */
+export interface RunStartInfo {
+    minHours: number;
+    baseSha: string;
+}
+export interface RoundFinishInfo {
+    outcome: RoundOutcome;
+    itemTitle: string;
+    elapsedMs: number;
+    remainingMs: number;
+}
+export interface RunEndInfo {
+    totals: RunTotals;
+    elapsedMs: number;
+    branch: string;
+    stopReason: string;
+}
+/** The hook surface the round runner drives. Implementations must not throw. */
+export interface RunProgressNotifier {
+    runStarted(info: RunStartInfo): Promise<void>;
+    roundFinished(info: RoundFinishInfo): Promise<void>;
+    runEnded(info: RunEndInfo): Promise<void>;
+}
+/** What delivery looks like from here: `ChannelDispatcher.send`, or a test double. */
+export interface CadenceSender {
+    send(text: string): Promise<unknown>;
+}
+export declare class CadenceNotifier implements RunProgressNotifier {
+    private readonly everyMin;
+    private readonly sender;
+    private readonly now;
+    private readonly window;
+    private lastReportAt;
+    private lastItem;
+    constructor(everyMin: number, sender: CadenceSender, now: () => number);
+    private get silent();
+    runStarted(info: RunStartInfo): Promise<void>;
+    roundFinished(info: RoundFinishInfo): Promise<void>;
+    runEnded(info: RunEndInfo): Promise<void>;
+    private deliver;
+}
+//# sourceMappingURL=notify-cadence.d.ts.map

package/dist/notify-cadence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify-cadence.d.ts","sourceRoot":"","sources":["../src/notify-cadence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG5D;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,qBAAa,eAAgB,YAAW,mBAAmB;IAMvD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAuB;gBAGpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,aAAa,EACrB,GAAG,EAAE,MAAM,MAAM;IAGpC,OAAO,KAAK,MAAM,GAEjB;IAEK,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBnD,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAajC,OAAO;CAStB"}

package/dist/notify-cadence.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CadenceNotifier = void 0;
+const notify_1 = require("./notify");
+class CadenceNotifier {
+    everyMin;
+    sender;
+    now;
+    window = new notify_1.NotifyWindow();
+    lastReportAt = 0;
+    lastItem = null;
+    constructor(everyMin, sender, now) {
+        this.everyMin = everyMin;
+        this.sender = sender;
+        this.now = now;
+    }
+    get silent() {
+        return this.everyMin <= 0;
+    }
+    async runStarted(info) {
+        if (this.silent)
+            return;
+        // The start line counts as a report: the first window is measured from it,
+        // so a 30min cadence does not fire twice in the opening minute.
+        this.lastReportAt = this.now();
+        await this.deliver((0, notify_1.formatStartReport)({ minHours: info.minHours, baseSha: info.baseSha, everyMin: this.everyMin }));
+    }
+    async roundFinished(info) {
+        if (this.silent)
+            return;
+        this.window.record(info.outcome);
+        this.lastItem = info.itemTitle;
+        if (this.now() - this.lastReportAt < this.everyMin * 60_000)
+            return;
+        const text = (0, notify_1.formatWindowReport)({
+            counts: this.window.counts,
+            lastItem: this.lastItem,
+            elapsedMs: info.elapsedMs,
+            remainingMs: info.remainingMs,
+        });
+        this.lastReportAt = this.now();
+        this.window.reset();
+        await this.deliver(text);
+    }
+    async runEnded(info) {
+        if (this.silent)
+            return;
+        await this.deliver((0, notify_1.formatEndReport)({
+            counts: info.totals,
+            elapsedMs: info.elapsedMs,
+            rounds: info.totals.rounds,
+            branch: info.branch,
+            stopReason: info.stopReason,
+        }));
+    }
+    async deliver(text) {
+        try {
+            await this.sender.send(text);
+        }
+        catch {
+            // ChannelDispatcher already resolves on every failure (§12 case 33), but
+            // this class is the last line between "reporting broke" and "the run
+            // died", so it does not rely on the sender honouring that contract.
+        }
+    }
+}
+exports.CadenceNotifier = CadenceNotifier;
+//# sourceMappingURL=notify-cadence.js.map

package/dist/notify-cadence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify-cadence.js","sourceRoot":"","sources":["../src/notify-cadence.ts"],"names":[],"mappings":";;;AACA,qCAAgG;AA+ChG,MAAa,eAAe;IAMP;IACA;IACA;IAPF,MAAM,GAAG,IAAI,qBAAY,EAAE,CAAC;IACrC,YAAY,GAAG,CAAC,CAAC;IACjB,QAAQ,GAAkB,IAAI,CAAC;IAEvC,YACmB,QAAgB,EAChB,MAAqB,EACrB,GAAiB;QAFjB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAe;QACrB,QAAG,GAAH,GAAG,CAAc;IACjC,CAAC;IAEJ,IAAY,MAAM;QAChB,OAAO,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,IAAkB;QACjC,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,2EAA2E;QAC3E,gEAAgE;QAChE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/B,MAAM,IAAI,CAAC,OAAO,CAAC,IAAA,0BAAiB,EAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACrH,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,IAAqB;QACvC,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC/B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,QAAQ,GAAG,MAAM;YAAE,OAAO;QACpE,MAAM,IAAI,GAAG,IAAA,2BAAkB,EAAC;YAC9B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAgB;QAC7B,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,MAAM,IAAI,CAAC,OAAO,CAChB,IAAA,wBAAe,EAAC;YACd,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC1B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CACH,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,IAAY;QAChC,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,qEAAqE;YACrE,oEAAoE;QACtE,CAAC;IACH,CAAC;CACF;AA7DD,0CA6DC"}

package/dist/notify-channel.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The channel dispatcher: the piece that actually delivers a notification.
+ *
+ * It shells out to `~/.looply/notify/<channel>.sh <text> [dest]` — outside the
+ * target repo, because the discard path runs `git clean -fd` and would otherwise
+ * delete it (DESIGN §3.2) — and maps the script's exit code onto the four
+ * outcomes of DESIGN §5.1: 0 sent, 1 config, 2 rejected, 3 network.
+ *
+ * The one property everything here serves: **no notifier failure may stop the
+ * run** (DESIGN §12 cases 33–34). `send` resolves on every path — rejection,
+ * missing script, spawn failure, hang — because the run is worth more than the
+ * reporting about it.
+ */
+export type NotifyOutcome = 'sent' | 'config' | 'rejected' | 'network';
+export interface DispatchResult {
+    outcome: NotifyOutcome;
+    /** The script's raw exit code; null when it never exited on its own. */
+    code: number | null;
+    /** Why, on every outcome other than `sent`. */
+    detail: string | null;
+}
+/** What running the channel script produced, before any interpretation. */
+export interface NotifyExecResult {
+    code: number | null;
+    timedOut: boolean;
+    /** Spawn-level failure message, when the script never ran at all. */
+    error?: string;
+}
+export type NotifyExec = (scriptPath: string, args: readonly string[], timeoutMs: number) => Promise<NotifyExecResult>;
+export interface NotifyChannelDeps {
+    exec: NotifyExec;
+    fileExists(path: string): boolean;
+    /** Where preflight warnings and failed sends land; the only trace they leave. */
+    log(line: string): void;
+    homeDir: string;
+}
+/**
+ * A notification is quick or it is abandoned: a gateway that hangs for minutes
+ * must not stretch every round by that much, so the script gets a short leash
+ * and the same group-kill a hung gate step gets.
+ */
+export declare const NOTIFY_TIMEOUT_MS = 30000;
+export declare function channelScriptPath(homeDir: string, channel: string): string;
+/** Map one execution onto the four outcomes. Anything off-contract is `config`. */
+export declare function outcomeForExec(r: NotifyExecResult): DispatchResult;
+export declare class ChannelDispatcher {
+    private readonly deps;
+    private readonly channel;
+    private disabled;
+    private readonly scriptPath;
+    private readonly channelValid;
+    constructor(deps: NotifyChannelDeps, channel: string);
+    /**
+     * DESIGN §12 case 34: a missing notifier at preflight is a warning and a
+     * disabled channel, never a refusal to run. Returns true when the channel is
+     * usable.
+     */
+    preflight(): boolean;
+    /**
+     * Deliver one message. Resolves on every path — a notifier failure is logged
+     * and returned, never thrown, because a dead gateway must not stop the loop
+     * (DESIGN §12 case 33).
+     */
+    send(text: string, dest?: string): Promise<DispatchResult>;
+}
+/** The real exec: argv-array, no shell, so a message body with quotes or `$` in
+ * an item title arrives as one literal argument instead of shell syntax. */
+export declare function nodeNotifyExec(scriptPath: string, args: readonly string[], timeoutMs: number): Promise<NotifyExecResult>;
+//# sourceMappingURL=notify-channel.d.ts.map

package/dist/notify-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify-channel.d.ts","sourceRoot":"","sources":["../src/notify-channel.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,CAAC;IACvB,wEAAwE;IACxE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,CACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,iFAAiF;IACjF,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAS,CAAC;AASxC,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,CAAC,EAAE,gBAAgB,GAAG,cAAc,CA2BlE;AAED,qBAAa,iBAAiB;IAM1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;gBAGpB,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,MAAM;IAOlC;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAcpB;;;;OAIG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAkBjE;AAED;4EAC4E;AAC5E,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,CAAC,CAiC3B"}

package/dist/notify-channel.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChannelDispatcher = exports.NOTIFY_TIMEOUT_MS = void 0;
+exports.channelScriptPath = channelScriptPath;
+exports.outcomeForExec = outcomeForExec;
+exports.nodeNotifyExec = nodeNotifyExec;
+const exec_domains_1 = require("./exec-domains");
+const node_child_process_1 = require("node:child_process");
+const command_runner_1 = require("./command-runner");
+const notify_1 = require("./notify");
+/**
+ * A notification is quick or it is abandoned: a gateway that hangs for minutes
+ * must not stretch every round by that much, so the script gets a short leash
+ * and the same group-kill a hung gate step gets.
+ */
+exports.NOTIFY_TIMEOUT_MS = 30_000;
+/**
+ * The channel name comes from user-editable config.yaml and is interpolated
+ * into a path, so it must be a bare name — `../../x` would execute an arbitrary
+ * script as the runner.
+ */
+const CHANNEL_NAME = /^[A-Za-z0-9_-]+$/;
+function channelScriptPath(homeDir, channel) {
+    return `${homeDir}/.looply/notify/${channel}.sh`;
+}
+/** Map one execution onto the four outcomes. Anything off-contract is `config`. */
+function outcomeForExec(r) {
+    if (r.error !== undefined) {
+        return { outcome: 'config', code: null, detail: `channel script failed to start: ${r.error}` };
+    }
+    if (r.timedOut) {
+        // A gateway that never answers is a network problem, not a config one — the
+        // script was fine yesterday and will be fine when the network returns.
+        return { outcome: 'network', code: null, detail: `channel script hung past ${exports.NOTIFY_TIMEOUT_MS}ms — killed` };
+    }
+    switch (r.code) {
+        case notify_1.NOTIFY_EXIT.sent:
+            return { outcome: 'sent', code: r.code, detail: null };
+        case notify_1.NOTIFY_EXIT.config:
+            return { outcome: 'config', code: r.code, detail: 'channel reports a configuration problem' };
+        case notify_1.NOTIFY_EXIT.rejected:
+            return { outcome: 'rejected', code: r.code, detail: 'gateway rejected the message' };
+        case notify_1.NOTIFY_EXIT.network:
+            return { outcome: 'network', code: r.code, detail: 'network failure reaching the gateway' };
+        default:
+            // An exit code outside the contract means the script is broken, and a
+            // broken script must never read as delivered.
+            return {
+                outcome: 'config',
+                code: r.code,
+                detail: r.code === null ? 'channel script died to a signal' : `unexpected exit code ${r.code}`,
+            };
+    }
+}
+class ChannelDispatcher {
+    deps;
+    channel;
+    disabled = false;
+    scriptPath;
+    channelValid;
+    constructor(deps, channel) {
+        this.deps = deps;
+        this.channel = channel;
+        this.channelValid = CHANNEL_NAME.test(channel);
+        // An invalid name never reaches the filesystem, whether or not preflight ran.
+        this.scriptPath = this.channelValid ? channelScriptPath(deps.homeDir, channel) : '';
+    }
+    /**
+     * DESIGN §12 case 34: a missing notifier at preflight is a warning and a
+     * disabled channel, never a refusal to run. Returns true when the channel is
+     * usable.
+     */
+    preflight() {
+        if (!this.channelValid) {
+            this.deps.log(`notify: channel name ${JSON.stringify(this.channel)} is not a bare name — channel disabled`);
+            this.disabled = true;
+            return false;
+        }
+        if (!this.deps.fileExists(this.scriptPath)) {
+            this.deps.log(`notify: ${this.scriptPath} not found — channel disabled, running anyway`);
+            this.disabled = true;
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Deliver one message. Resolves on every path — a notifier failure is logged
+     * and returned, never thrown, because a dead gateway must not stop the loop
+     * (DESIGN §12 case 33).
+     */
+    async send(text, dest) {
+        if (this.disabled || !this.channelValid) {
+            // Not logged per send: preflight already warned once, and a disabled
+            // channel firing every window would fill the log with the same line.
+            return { outcome: 'config', code: null, detail: 'channel disabled' };
+        }
+        let r;
+        try {
+            r = await this.deps.exec(this.scriptPath, dest === undefined ? [text] : [text, dest], exports.NOTIFY_TIMEOUT_MS);
+        }
+        catch (e) {
+            r = { code: null, timedOut: false, error: e instanceof Error ? e.message : String(e) };
+        }
+        const result = outcomeForExec(r);
+        if (result.outcome !== 'sent') {
+            this.deps.log(`notify(${this.channel}): ${result.outcome} — ${result.detail ?? 'no detail'}`);
+        }
+        return result;
+    }
+}
+exports.ChannelDispatcher = ChannelDispatcher;
+/** The real exec: argv-array, no shell, so a message body with quotes or `$` in
+ * an item title arrives as one literal argument instead of shell syntax. */
+function nodeNotifyExec(scriptPath, args, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            resolve(r);
+        };
+        const child = (0, node_child_process_1.spawn)(scriptPath, [...args], {
+            detached: process.platform !== 'win32',
+            stdio: 'ignore',
+            // NOT CONTAINED, and deliberately so: this script is the person's own,
+            // stored under their home directory, and running it is the product
+            // working. But it was inheriting the daemon's entire environment — the
+            // machine token included — to send a message. A notification has never
+            // needed a credential.
+            // Cast because a type in node_modules augments NodeJS.ProcessEnv with
+            // required members, so no explicit record satisfies it. The value is an
+            // ordinary environment; the assertion is about that declaration, not
+            // about the contents.
+            env: (0, exec_domains_1.buildNotifyEnv)(),
+        });
+        child.on('error', (err) => finish({ code: null, timedOut: false, error: err.message }));
+        child.on('exit', (code) => finish({ code, timedOut: false }));
+        timer = setTimeout(() => {
+            // Same rationale as the gate's runner: kill the group and resolve now — a
+            // script that survives the kill is exactly the hang being escaped.
+            if (child.pid !== undefined)
+                (0, command_runner_1.nodeKillTree)(child.pid);
+            finish({ code: null, timedOut: true });
+        }, timeoutMs);
+    });
+}
+//# sourceMappingURL=notify-channel.js.map

package/dist/notify-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify-channel.js","sourceRoot":"","sources":["../src/notify-channel.ts"],"names":[],"mappings":"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"}

package/dist/notify.d.ts

@@ -0,0 +1,71 @@
+import type { RoundOutcome } from '@looply/core';
+export declare function foldAscii(input: string): string;
+export declare function truncate(text: string, cap: number): string;
+/** Prepare a body for a channel: folded, single-line, capped. Never split. */
+export declare function prepareBody(text: string, cap?: number): string;
+export declare function formatDurationHm(ms: number): string;
+/**
+ * Counters for one reporting window.
+ *
+ * Windowed rather than cumulative so each message describes its own interval —
+ * a cumulative tally makes a stalled hour look identical to a productive one.
+ */
+export declare class NotifyWindow {
+    private committed;
+    private abandoned;
+    private discarded;
+    private rounds;
+    record(outcome: RoundOutcome): void;
+    get counts(): {
+        committed: number;
+        abandoned: number;
+        discarded: number;
+        rounds: number;
+    };
+    reset(): void;
+}
+export interface WindowReport {
+    counts: {
+        committed: number;
+        abandoned: number;
+        discarded: number;
+        rounds: number;
+    };
+    lastItem: string | null;
+    elapsedMs: number;
+    remainingMs: number;
+    itemCap?: number;
+}
+/**
+ * One line of progress.
+ *
+ * A window in which nothing finished says so explicitly and names what it is still
+ * on — silence and slowness must not look the same.
+ */
+export declare function formatWindowReport(r: WindowReport): string;
+export declare function formatStartReport(opts: {
+    minHours: number;
+    baseSha: string;
+    everyMin: number;
+}): string;
+export declare function formatEndReport(opts: {
+    counts: {
+        committed: number;
+        abandoned: number;
+        discarded: number;
+    };
+    elapsedMs: number;
+    rounds: number;
+    branch: string;
+    stopReason: string;
+}): string;
+/** Exit codes from a notifier channel. A dead gateway must never stop the loop. */
+export declare const NOTIFY_EXIT: {
+    readonly sent: 0;
+    readonly config: 1;
+    readonly rejected: 2;
+    readonly network: 3;
+};
+export type NotifyExit = (typeof NOTIFY_EXIT)[keyof typeof NOTIFY_EXIT];
+export declare function isFatalToLoop(_code: NotifyExit): boolean;
+//# sourceMappingURL=notify.d.ts.map

package/dist/notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.d.ts","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAgCjD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAK;IAEnB,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAOnC,IAAI,MAAM,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAOxF;IAED,KAAK,IAAI,IAAI;CAMd;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAU1D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAIvG;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAMT;AAED,mFAAmF;AACnF,eAAO,MAAM,WAAW;;;;;CAA2D,CAAC;AACpF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAExE,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAExD"}

package/dist/notify.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOTIFY_EXIT = exports.NotifyWindow = void 0;
+exports.foldAscii = foldAscii;
+exports.truncate = truncate;
+exports.prepareBody = prepareBody;
+exports.formatDurationHm = formatDurationHm;
+exports.formatWindowReport = formatWindowReport;
+exports.formatStartReport = formatStartReport;
+exports.formatEndReport = formatEndReport;
+exports.isFatalToLoop = isFatalToLoop;
+/**
+ * Progress reporting.
+ *
+ * This lives in the runner rather than in a supervising agent session, because a
+ * run that goes quiet is the worst failure mode and reporting must survive the
+ * supervising terminal being closed. The message format is deliberately readable
+ * on a lock screen without opening anything.
+ */
+/**
+ * Fold to ASCII.
+ *
+ * The SMS gateway rejects non-ASCII bodies outright, and item titles are full of
+ * em dashes and curly quotes. Each character is replaced individually and never
+ * via a character class: a byte-oriented replacement over a class would rewrite
+ * each of an em dash's three UTF-8 bytes and produce `---`.
+ */
+const FOLD = [
+    ['—', '-'], // em dash
+    ['–', '-'], // en dash
+    ['‘', "'"], // left single quote
+    ['’', "'"], // right single quote
+    ['“', '"'], // left double quote
+    ['”', '"'], // right double quote
+    ['…', '...'], // ellipsis
+    [' ', ' '], // non-breaking space
+    ['•', '*'], // bullet
+    ['·', '-'], // middle dot
+];
+function foldAscii(input) {
+    let out = input;
+    for (const [from, to] of FOLD)
+        out = out.split(from).join(to);
+    // Anything left outside printable ASCII is dropped rather than mangled.
+    return out.replace(/[\r\n]+/g, ' ').replace(/[^\x20-\x7E]/g, '');
+}
+function truncate(text, cap) {
+    return text.length <= cap ? text : text.slice(0, cap);
+}
+/** Prepare a body for a channel: folded, single-line, capped. Never split. */
+function prepareBody(text, cap = 280) {
+    return truncate(foldAscii(text).replace(/\s+/g, ' ').trim(), cap);
+}
+function formatDurationHm(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    return `${h}h${String(m).padStart(2, '0')}m`;
+}
+/**
+ * Counters for one reporting window.
+ *
+ * Windowed rather than cumulative so each message describes its own interval —
+ * a cumulative tally makes a stalled hour look identical to a productive one.
+ */
+class NotifyWindow {
+    committed = 0;
+    abandoned = 0;
+    discarded = 0;
+    rounds = 0;
+    record(outcome) {
+        this.rounds += 1;
+        if (outcome === 'committed')
+            this.committed += 1;
+        else if (outcome === 'abandoned')
+            this.abandoned += 1;
+        else
+            this.discarded += 1;
+    }
+    get counts() {
+        return {
+            committed: this.committed,
+            abandoned: this.abandoned,
+            discarded: this.discarded,
+            rounds: this.rounds,
+        };
+    }
+    reset() {
+        this.committed = 0;
+        this.abandoned = 0;
+        this.discarded = 0;
+        this.rounds = 0;
+    }
+}
+exports.NotifyWindow = NotifyWindow;
+/**
+ * One line of progress.
+ *
+ * A window in which nothing finished says so explicitly and names what it is still
+ * on — silence and slowness must not look the same.
+ */
+function formatWindowReport(r) {
+    const { committed, abandoned, discarded, rounds } = r.counts;
+    const head = `[${committed}][${abandoned}][${discarded}]`;
+    const item = r.lastItem ? truncate(foldAscii(r.lastItem), r.itemCap ?? 60) : 'nothing yet';
+    const what = rounds === 0
+        ? `no round finished this window, still on: ${item}`
+        : `${rounds} rounds, last: ${item}`;
+    const tail = `(${formatDurationHm(r.elapsedMs)} in, ${Math.max(0, Math.floor(r.remainingMs / 60000))}min left)`;
+    return prepareBody(`${head} - ${what} ${tail}`);
+}
+function formatStartReport(opts) {
+    return prepareBody(`[0][0][0] - looply started, ${opts.minHours}h min from ${opts.baseSha.slice(0, 7)}, reports every ${opts.everyMin}min`);
+}
+function formatEndReport(opts) {
+    const { committed, abandoned, discarded } = opts.counts;
+    return prepareBody(`[${committed}][${abandoned}][${discarded}] - looply DONE ${formatDurationHm(opts.elapsedMs)}, ` +
+        `${opts.rounds} rounds on ${opts.branch} (${opts.stopReason}), not pushed`);
+}
+/** Exit codes from a notifier channel. A dead gateway must never stop the loop. */
+exports.NOTIFY_EXIT = { sent: 0, config: 1, rejected: 2, network: 3 };
+function isFatalToLoop(_code) {
+    return false;
+}
+//# sourceMappingURL=notify.js.map

package/dist/notify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notify.js","sourceRoot":"","sources":["../src/notify.ts"],"names":[],"mappings":"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"}

package/dist/observation-inventory.d.ts

@@ -0,0 +1,65 @@
+import { type Artifact, type ArtifactClass } from '@looply/core';
+/**
+ * OBSERVATIONS, AS ARTIFACTS THE RETENTION POLICY CAN SEE.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE ROOT EXISTED AND NOTHING WAS POINTED AT IT.
+ * `session-observation-store.ts` says so itself: *"its own root, one file per
+ * watch, and a root a retention policy can be pointed at — this product already
+ * decided how disposable artifacts are removed (D5), and an observation is
+ * exactly that kind of artifact."* `looply evidence` inventoried two folders and
+ * listed `observations/` under *uninventoried*. That is honest reporting of an
+ * unbounded store, and `OWNER_CHARTER.md` §5 D5 asks for more than honesty:
+ * *"Also cover the named compile/tool/rejected stores or report exact
+ * unclassified entries; do not claim complete retention from an inventory of
+ * only two folders."*
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ⚠️ THE UNIT IS ONE WATCH, NOT ONE SESSION. A session directory holds a file
+ * per watch, taken at different times and ending in different ways — a
+ * directory-level decision would either keep a year-old complete account
+ * because a recent watch sits beside it, or expire a record that is still
+ * running. So the artifact id is `<sessionId>/<file>`, which is also the path
+ * under the store, so `pathOf` resolves without a second convention.
+ *
+ * 🔴 AND NOTHING UNREADABLE BECOMES AN ARTIFACT. *"Missing/unreadable/unknown
+ * is never deletion permission."* A file that cannot be parsed, a link, a
+ * `coversFrom` that is not a time — each is NAMED here and left out of the
+ * plan, which is the only way a policy can be wrong about it in the safe
+ * direction.
+ */
+export declare const OBSERVATIONS_STORE = "observations";
+export interface ObservationInventory {
+    /** What the policy may decide about. */
+    readonly artifacts: readonly Artifact[];
+    /** What it may not, with the reason. Reported, never planned over. */
+    readonly unreadable: readonly string[];
+}
+/**
+ * Every watch on file, classified.
+ *
+ * ⚠️ `createdAtMs` IS `coversFrom`, NOT THE FILE'S MTIME. The record is written
+ * twice — once at attach and once at the close — so its mtime is the moment the
+ * watch ENDED, and a long watch would look hours younger than it is. What the
+ * age window is about is when the observation began.
+ */
+export declare function inventoryObservations(stateDir: string): ObservationInventory;
+/**
+ * The re-check `--apply` makes immediately before removing one.
+ *
+ * 🔴 D5: *"check identity, ownership, current policy eligibility, pins,
+ * references and path boundaries AGAIN before removal."* The plan was made from
+ * a walk that may be minutes old; a watch that has since been re-opened, or a
+ * record replaced by something that is not one, must not be removed on the
+ * strength of what was true then.
+ *
+ * `null` means "this is not an observation this inventory owns" — an id that
+ * could leave the store, a session with no such file, a file that no longer
+ * parses. The caller must treat that as a refusal, never as permission.
+ */
+export declare function observationFacts(stateDir: string, id: string): {
+    owned: boolean;
+    pinned: boolean;
+    class: ArtifactClass;
+} | null;
+//# sourceMappingURL=observation-inventory.d.ts.map

package/dist/observation-inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-inventory.d.ts","sourceRoot":"","sources":["../src/observation-inventory.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0B,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAGzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAcD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAkD5E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAAG,IAAI,CAYlE"}