shreni 0.1.0

package/dist/sthapathi/watchdog.js

@@ -0,0 +1,145 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_OUTCOME_REPEAT = exports.STUCK_THRESHOLD_MS = void 0;
+exports.remediationFor = remediationFor;
+exports.evaluateStuck = evaluateStuck;
+exports.runWatchdogOnce = runWatchdogOnce;
+const fs_1 = require("fs");
+const state_js_1 = require("../kshetra/state.js");
+const activity_log_js_1 = require("./activity-log.js");
+const errors_js_1 = require("./errors.js");
+// Defaults per the Sthapathi workflow design §4.4 / D1. Made configurable
+// per-Kshetra later.
+exports.STUCK_THRESHOLD_MS = 20 * 60 * 1000; // 20m of no liveness while busy
+exports.MAX_OUTCOME_REPEAT = 5; // same non-advancing outcome this many times
+// Human-facing remediation steps for a given stall outcome. Generic fallback
+// covers a hung agent / unknown stall.
+function remediationFor(outcome) {
+    const o = outcome ?? '';
+    if (o.includes('branch already exists')) {
+        return [
+            '  1) Delete the stale bead branch, then resume:',
+            '       git -C <repo> branch -D <bead-branch>',
+            '       shreni resume --kshetra <id>',
+            '  2) If it recurs, the worker will RECOVER it on next start (shreni stop/start).',
+        ].join('\n');
+    }
+    if (o.includes('dirty working tree')) {
+        return [
+            '  1) Inspect, then discard the interrupted changes:',
+            '       git -C <repo> status',
+            '       git -C <repo> checkout main && git -C <repo> clean -fd',
+            '  2) shreni resume --kshetra <id>  (RECOVER also cleans this on restart)',
+        ].join('\n');
+    }
+    if (o.includes('cycle:GIT_FAILED') || o.includes('cycle:BD_FAILED')) {
+        return [
+            '  1) Read the error in the worker log; fix the underlying git/bd issue.',
+            '  2) shreni resume --kshetra <id>',
+        ].join('\n');
+    }
+    if (o.includes('base suite red') || o.includes('health')) {
+        return [
+            '  1) A [shreni-health] repair bead should be queued — let it run, or',
+            '  2) fix the failing tests manually, then shreni resume --kshetra <id>.',
+        ].join('\n');
+    }
+    // One honest clearing verb — ACK — named everywhere (the watchdog design §3.3 /
+    // RC3). The latch clears only on an explicit human acknowledgment, exposed two
+    // ways that both funnel to resumeKshetra: the CLI, and a deliberate stop/start
+    // (RECOVER acknowledges the drift, then clears it).
+    return [
+        '  1) Inspect the worker log and the active bead for a genuinely hung agent.',
+        '  2) ACK to clear the latch and resume — either of:',
+        '       shreni resume --kshetra <id>          (CLI ACK)',
+        '       shreni stop --kshetra <id> && shreni start --kshetra <id>  (RECOVER acknowledges)',
+        '  3) If a specific bead keeps failing, mark it blocked for manual work.',
+    ].join('\n');
+}
+// Pure decision: is the worker stuck? Two independent trip conditions — a fast
+// stall loop (same outcome repeated) and a liveness timeout (no activity while
+// the worker should be busy). A manually-paused Kshetra is never "stuck" (it is
+// already awaiting a human).
+function evaluateStuck(input) {
+    if (input.manuallyPaused)
+        return { stuck: false };
+    // Idle by design: an empty ready queue with nothing in flight. "No activity"
+    // here means "nothing to do", not "hung" — never trip, so the watchdog never
+    // escalates an idle worker to Phalaka. A genuine
+    // hang while WORKING/PREPARING, or a repeat-stall with ready work waiting, is
+    // not idle (idleNoWork is false there) and still trips below.
+    if (input.idleNoWork)
+        return { stuck: false };
+    const stuckMs = input.thresholds?.stuckMs ?? exports.STUCK_THRESHOLD_MS;
+    const maxRepeat = input.thresholds?.maxRepeat ?? exports.MAX_OUTCOME_REPEAT;
+    if (input.outcomeRepeatCount >= maxRepeat) {
+        return {
+            stuck: true,
+            reason: `the same outcome "${input.lastOutcome ?? 'unknown'}" repeated ${input.outcomeRepeatCount}× without forward progress`,
+            remediation: remediationFor(input.lastOutcome),
+        };
+    }
+    if (input.phase !== 'IDLE' && input.heartbeatAgeMs !== null && input.heartbeatAgeMs > stuckMs) {
+        const mins = Math.round(input.heartbeatAgeMs / 60_000);
+        return {
+            stuck: true,
+            reason: `no worker heartbeat for ${mins}m while phase=${input.phase} — the worker appears hung`,
+            remediation: remediationFor(undefined),
+        };
+    }
+    return { stuck: false };
+}
+// Worker liveness = age of the heartbeat file's mtime (the watchdog design §3.1).
+// Falls back to the legacy activity.jsonl mtime only when no heartbeat exists yet, so
+// an old worker (or the first tick before the first stamp) degrades gracefully rather
+// than reading as a fresh worker that can never trip.
+function heartbeatAge(kshetraId, now) {
+    try {
+        return now - (0, fs_1.statSync)((0, activity_log_js_1.heartbeatPath)(kshetraId)).mtimeMs;
+    }
+    catch {
+        // no heartbeat file — fall back to agent-emit liveness (legacy behavior)
+    }
+    try {
+        return now - (0, fs_1.statSync)((0, activity_log_js_1.logPath)(kshetraId)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+// Evaluate once and, on a fresh trip, escalate: set the stuck banner (Phalaka),
+// pause for manual resume, and push an operator notification with remediation.
+// Idempotent — does not re-notify while already flagged stuck.
+async function runWatchdogOnce(kshetra, getPhase, now = Date.now(), opts) {
+    const progress = (0, state_js_1.getProgressState)(kshetra);
+    if (progress.stuck)
+        return { stuck: true, reason: progress.stuck.reason };
+    const phase = getPhase();
+    // Distinguish "idle because there's nothing to do" from "hung". Only IDLE and
+    // SELECTING can be idle-by-design; PREPARING/WORKING always have a task in
+    // flight, so we skip the ready-queue probe (and its bd call) on busy ticks.
+    // When the probe reports an empty queue, inactivity is expected — not stuck.
+    let idleNoWork = false;
+    if ((phase === 'IDLE' || phase === 'SELECTING') && opts?.hasReadyWork) {
+        idleNoWork = !(await opts.hasReadyWork());
+    }
+    const verdict = evaluateStuck({
+        phase,
+        manuallyPaused: (0, state_js_1.isKshetraManuallyPaused)(kshetra),
+        heartbeatAgeMs: heartbeatAge(kshetra.id, now),
+        outcomeRepeatCount: progress.outcomeRepeatCount,
+        lastOutcome: progress.lastOutcome,
+        idleNoWork,
+        thresholds: {
+            stuckMs: kshetra.watchdog?.stuckThresholdMs,
+            maxRepeat: kshetra.watchdog?.maxOutcomeRepeat,
+        },
+    });
+    if (verdict.stuck && verdict.reason && verdict.remediation) {
+        (0, state_js_1.setStuck)(kshetra, { reason: verdict.reason, remediation: verdict.remediation, phase });
+        (0, state_js_1.pauseKshetra)(kshetra, { reason: 'stuck', message: verdict.reason, manual: true });
+        await (0, errors_js_1.notifyOperator)(kshetra, null, 'stuck', verdict.reason, verdict.remediation);
+    }
+    return verdict;
+}
+//# sourceMappingURL=watchdog.js.map

package/dist/sthapathi/watchdog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdog.js","sourceRoot":"","sources":["../../src/sthapathi/watchdog.ts"],"names":[],"mappings":";;;AAoCA,wCAyCC;AAMD,sCA+BC;AAsBD,0CAuCC;AA/KD,2BAA8B;AAG9B,kDAAwG;AACxG,uDAA2D;AAC3D,2CAA6C;AAE7C,0EAA0E;AAC1E,qBAAqB;AACR,QAAA,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gCAAgC;AACrE,QAAA,kBAAkB,GAAG,CAAC,CAAC,CAAC,6CAA6C;AAwBlF,6EAA6E;AAC7E,uCAAuC;AACvC,SAAgB,cAAc,CAAC,OAA2B;IACxD,MAAM,CAAC,GAAG,OAAO,IAAI,EAAE,CAAC;IACxB,IAAI,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC;QACxC,OAAO;YACL,iDAAiD;YACjD,8CAA8C;YAC9C,qCAAqC;YACrC,kFAAkF;SACnF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACrC,OAAO;YACL,qDAAqD;YACrD,6BAA6B;YAC7B,+DAA+D;YAC/D,0EAA0E;SAC3E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;QACpE,OAAO;YACL,yEAAyE;YACzE,mCAAmC;SACpC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzD,OAAO;YACL,sEAAsE;YACtE,yEAAyE;SAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IACD,gFAAgF;IAChF,+EAA+E;IAC/E,+EAA+E;IAC/E,oDAAoD;IACpD,OAAO;QACL,6EAA6E;QAC7E,qDAAqD;QACrD,wDAAwD;QACxD,0FAA0F;QAC1F,yEAAyE;KAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,6BAA6B;AAC7B,SAAgB,aAAa,CAAC,KAAiB;IAC7C,IAAI,KAAK,CAAC,cAAc;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAElD,6EAA6E;IAC7E,6EAA6E;IAC7E,iDAAiD;IACjD,8EAA8E;IAC9E,8DAA8D;IAC9D,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAE9C,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,EAAE,OAAO,IAAI,0BAAkB,CAAC;IAChE,MAAM,SAAS,GAAG,KAAK,CAAC,UAAU,EAAE,SAAS,IAAI,0BAAkB,CAAC;IAEpE,IAAI,KAAK,CAAC,kBAAkB,IAAI,SAAS,EAAE,CAAC;QAC1C,OAAO;YACL,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,qBAAqB,KAAK,CAAC,WAAW,IAAI,SAAS,cAAc,KAAK,CAAC,kBAAkB,4BAA4B;YAC7H,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC,WAAW,CAAC;SAC/C,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,KAAK,KAAK,MAAM,IAAI,KAAK,CAAC,cAAc,KAAK,IAAI,IAAI,KAAK,CAAC,cAAc,GAAG,OAAO,EAAE,CAAC;QAC9F,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC,CAAC;QACvD,OAAO;YACL,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,2BAA2B,IAAI,iBAAiB,KAAK,CAAC,KAAK,4BAA4B;YAC/F,WAAW,EAAE,cAAc,CAAC,SAAS,CAAC;SACvC,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED,kFAAkF;AAClF,sFAAsF;AACtF,sFAAsF;AACtF,sDAAsD;AACtD,SAAS,YAAY,CAAC,SAAiB,EAAE,GAAW;IAClD,IAAI,CAAC;QACH,OAAO,GAAG,GAAG,IAAA,aAAQ,EAAC,IAAA,+BAAa,EAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;IACD,IAAI,CAAC;QACH,OAAO,GAAG,GAAG,IAAA,aAAQ,EAAC,IAAA,yBAAO,EAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,+EAA+E;AAC/E,+DAA+D;AACxD,KAAK,UAAU,eAAe,CACnC,OAAsB,EACtB,QAAqB,EACrB,MAAc,IAAI,CAAC,GAAG,EAAE,EACxB,IAA0D;IAE1D,MAAM,QAAQ,GAAG,IAAA,2BAAgB,EAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,QAAQ,CAAC,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;IAE1E,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IAEzB,8EAA8E;IAC9E,2EAA2E;IAC3E,4EAA4E;IAC5E,6EAA6E;IAC7E,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,CAAC,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,WAAW,CAAC,IAAI,IAAI,EAAE,YAAY,EAAE,CAAC;QACtE,UAAU,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC;QAC5B,KAAK;QACL,cAAc,EAAE,IAAA,kCAAuB,EAAC,OAAO,CAAC;QAChD,cAAc,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC;QAC7C,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;QAC/C,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,UAAU;QACV,UAAU,EAAE;YACV,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,gBAAgB;YAC3C,SAAS,EAAE,OAAO,CAAC,QAAQ,EAAE,gBAAgB;SAC9C;KACF,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QAC3D,IAAA,mBAAQ,EAAC,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;QACvF,IAAA,uBAAY,EAAC,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QAClF,MAAM,IAAA,0BAAc,EAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/telemetry/telemetry.d.ts

@@ -0,0 +1,42 @@
+export declare const TELEMETRY_ENDPOINT: string | null;
+export declare const CONSENT_NOTICE: string;
+export type TelemetryEventName = 'session_start' | 'kshetra_init' | 'task_merged';
+export interface TelemetryEvent {
+    name: TelemetryEventName;
+    ts: string;
+    anonymousId: string;
+    version: string;
+    platform: string;
+    props?: Record<string, string | number | boolean>;
+}
+export interface TelemetryConfig {
+    enabled: boolean;
+    anonymousId?: string;
+    consentedAt?: string;
+    endpoint?: string | null;
+}
+declare function configPath(dir: string): string;
+declare function localSinkPath(dir: string): string;
+export declare function loadTelemetryConfig(dir?: string): TelemetryConfig;
+export declare function isTelemetryEnabled(cfg: TelemetryConfig, env?: NodeJS.ProcessEnv): boolean;
+export interface EmitOpts {
+    dir?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function emit(name: TelemetryEventName, props?: Record<string, string | number | boolean>, opts?: EmitOpts): void;
+export declare function enableTelemetry(dir?: string): TelemetryConfig;
+export declare function disableTelemetry(dir?: string): TelemetryConfig;
+export interface TelemetryStatus {
+    enabled: boolean;
+    hardOptOut: boolean;
+    anonymousId?: string;
+    endpoint: string | null;
+    localSink: string;
+}
+export declare function telemetryStatus(dir?: string, env?: NodeJS.ProcessEnv): TelemetryStatus;
+export declare const _internal: {
+    configPath: typeof configPath;
+    localSinkPath: typeof localSinkPath;
+};
+export {};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,kBAAkB,EAAE,MAAM,GAAG,IAAW,CAAC;AAGtD,eAAO,MAAM,cAAc,QAUf,CAAC;AAGb,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,cAAc,GACd,aAAa,CAAC;AAElB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IAEjB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAMD,iBAAS,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEvC;AAED,iBAAS,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAqB,GAAG,eAAe,CAO/E;AAUD,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,eAAe,EACpB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAKT;AA2CD,MAAM,WAAW,QAAQ;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAMD,wBAAgB,IAAI,CAClB,IAAI,EAAE,kBAAkB,EACxB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EACjD,IAAI,GAAE,QAAa,GAClB,IAAI,CAsBN;AAID,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAqB,GAAG,eAAe,CAU3E;AAID,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAqB,GAAG,eAAe,CAK5E;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,eAAe,CAC7B,GAAG,GAAE,MAAqB,EAC1B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,CAWjB;AAGD,eAAO,MAAM,SAAS;;;CAAgC,CAAC"}

package/dist/telemetry/telemetry.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._internal = exports.CONSENT_NOTICE = exports.TELEMETRY_ENDPOINT = void 0;
+exports.loadTelemetryConfig = loadTelemetryConfig;
+exports.isTelemetryEnabled = isTelemetryEnabled;
+exports.emit = emit;
+exports.enableTelemetry = enableTelemetry;
+exports.disableTelemetry = disableTelemetry;
+exports.telemetryStatus = telemetryStatus;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const crypto_1 = require("crypto");
+// Opt-in, privacy-respecting telemetry (yds.5).
+//
+// Purpose: measure clone→first-merge *activation* and 7-day *retention* so the
+// team/monetization decisions after launch aren't made blind. Nothing else.
+//
+// Guarantees:
+//   • OFF by default. Nothing is sent until the user explicitly opts in
+//     (`shreni telemetry enable`) or sets SHRENI_TELEMETRY=1.
+//   • Respects a hard opt-out (DO_NOT_TRACK=1 or SHRENI_TELEMETRY=0), which wins
+//     over any config.
+//   • No PII, ever: no repo names, no paths, no code, no task content, no user
+//     identity. Only an anonymous random id, the event name, a coarse OS
+//     platform, the Shreni version, and whitelisted primitive props the caller
+//     passes explicitly.
+//   • emit() never throws and never blocks — a telemetry failure must never
+//     affect the harness.
+//
+// ─── FOUNDER DECISIONS (fill these in before relying on the data) ───
+//   1. TELEMETRY_ENDPOINT below is null: with no endpoint, an opted-in client
+//      writes events to a LOCAL jsonl file only (nothing leaves the machine).
+//      Set a real collector URL here (or via SHRENI_TELEMETRY_ENDPOINT) to
+//      actually gather activation/retention.
+//   2. CONSENT_NOTICE copy — the exact disclosure shown on `telemetry enable`.
+//   3. The set of event names (below) and any props — keep them non-identifying.
+// null → local-only sink (see above). A founder sets this to the collector URL,
+// or overrides per-run with SHRENI_TELEMETRY_ENDPOINT.
+exports.TELEMETRY_ENDPOINT = null;
+// Shown when a user runs `shreni telemetry enable`. FOUNDER: finalize this copy.
+exports.CONSENT_NOTICE = [
+    'Shreni telemetry is OPT-IN and anonymous.',
+    '',
+    'If you enable it, Shreni sends a random anonymous id plus coarse events',
+    '(e.g. "a project was initialised", "a task merged", "the harness started")',
+    'with the Shreni version and your OS platform. It NEVER sends your code, file',
+    'paths, repo names, task contents, or any personal identifier.',
+    '',
+    'This helps us understand activation and retention. You can turn it off any',
+    'time with `shreni telemetry disable`, or set DO_NOT_TRACK=1 to hard-disable it.',
+].join('\n');
+function defaultDir() {
+    return (0, path_1.resolve)((0, os_1.homedir)(), '.shreni');
+}
+function configPath(dir) {
+    return (0, path_1.join)(dir, 'telemetry.json');
+}
+function localSinkPath(dir) {
+    return (0, path_1.join)(dir, 'telemetry-local.jsonl');
+}
+function loadTelemetryConfig(dir = defaultDir()) {
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(configPath(dir), 'utf8'));
+    }
+    catch {
+        // Missing / unreadable config ⇒ the default: disabled (opt-in).
+        return { enabled: false };
+    }
+}
+function saveTelemetryConfig(cfg, dir = defaultDir()) {
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    (0, fs_1.writeFileSync)(configPath(dir), JSON.stringify(cfg, null, 2), 'utf8');
+}
+// Resolve the effective on/off state. A hard opt-out (DO_NOT_TRACK=1 or
+// SHRENI_TELEMETRY in {0,off,false}) always wins; an env opt-in
+// (SHRENI_TELEMETRY in {1,on,true}) forces on; otherwise the persisted config.
+function isTelemetryEnabled(cfg, env = process.env) {
+    const flag = (env.SHRENI_TELEMETRY ?? '').toLowerCase();
+    if (env.DO_NOT_TRACK === '1' || flag === '0' || flag === 'off' || flag === 'false')
+        return false;
+    if (flag === '1' || flag === 'on' || flag === 'true')
+        return true;
+    return cfg.enabled === true;
+}
+function resolveEndpoint(cfg, env) {
+    return env.SHRENI_TELEMETRY_ENDPOINT ?? cfg.endpoint ?? exports.TELEMETRY_ENDPOINT;
+}
+function readVersion() {
+    try {
+        const raw = (0, fs_1.readFileSync)((0, path_1.join)(__dirname, '..', '..', 'package.json'), 'utf8');
+        return JSON.parse(raw).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// Deliver one event. With an endpoint set, POST it (best-effort, short timeout,
+// failures swallowed). With no endpoint, append it to a local jsonl file so an
+// opted-in user can inspect exactly what would be sent — and nothing leaves the
+// machine until a collector URL is configured.
+async function deliver(event, endpoint, dir) {
+    if (!endpoint) {
+        try {
+            (0, fs_1.appendFileSync)(localSinkPath(dir), JSON.stringify(event) + '\n', 'utf8');
+        }
+        catch {
+            /* local sink is best-effort */
+        }
+        return;
+    }
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(event),
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+    }
+    catch {
+        /* telemetry must never surface a failure to the caller */
+    }
+}
+// Record an event. A no-op (and a synchronous early return) when telemetry is
+// disabled — the default — so the hot path pays almost nothing. Fully guarded:
+// never throws, never blocks (network delivery is fire-and-forget; the local
+// sink write is synchronous but cheap).
+function emit(name, props, opts = {}) {
+    try {
+        const dir = opts.dir ?? defaultDir();
+        const env = opts.env ?? process.env;
+        const cfg = loadTelemetryConfig(dir);
+        if (!isTelemetryEnabled(cfg, env))
+            return;
+        const event = {
+            name,
+            ts: new Date().toISOString(),
+            anonymousId: cfg.anonymousId ?? 'anonymous',
+            version: readVersion(),
+            platform: process.platform,
+            ...(props ? { props } : {}),
+        };
+        // Fire-and-forget: swallow the promise so a slow/failed POST never blocks or
+        // rejects into the caller. (The no-endpoint local-sink path runs
+        // synchronously before the promise is returned.)
+        void deliver(event, resolveEndpoint(cfg, env), dir);
+    }
+    catch {
+        /* telemetry must never break the caller */
+    }
+}
+// Turn telemetry on: persist enabled=true, mint a stable anonymous id on first
+// opt-in (reused thereafter), and stamp the consent time. Returns the new config.
+function enableTelemetry(dir = defaultDir()) {
+    const cfg = loadTelemetryConfig(dir);
+    const next = {
+        ...cfg,
+        enabled: true,
+        anonymousId: cfg.anonymousId ?? (0, crypto_1.randomUUID)(),
+        consentedAt: new Date().toISOString(),
+    };
+    saveTelemetryConfig(next, dir);
+    return next;
+}
+// Turn telemetry off. Keeps the anonymous id so a later re-opt-in is the same
+// install (not a new one), but stops all sending.
+function disableTelemetry(dir = defaultDir()) {
+    const cfg = loadTelemetryConfig(dir);
+    const next = { ...cfg, enabled: false };
+    saveTelemetryConfig(next, dir);
+    return next;
+}
+function telemetryStatus(dir = defaultDir(), env = process.env) {
+    const cfg = loadTelemetryConfig(dir);
+    const hardOptOut = env.DO_NOT_TRACK === '1' || ['0', 'off', 'false'].includes((env.SHRENI_TELEMETRY ?? '').toLowerCase());
+    return {
+        enabled: isTelemetryEnabled(cfg, env),
+        hardOptOut,
+        anonymousId: cfg.anonymousId,
+        endpoint: resolveEndpoint(cfg, env),
+        localSink: localSinkPath(dir),
+    };
+}
+// Exposed for tests (config path + local sink path resolution).
+exports._internal = { configPath, localSinkPath };
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry/telemetry.js.map

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

package/dist/test-setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test-setup.d.ts.map

package/dist/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":""}

package/dist/test-setup.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+// Isolate the home directory for the whole test process so nothing can write
+// into the developer's real `~/.shreni` (activity logs, kshetra state, etc.).
+//
+// `os.homedir()` reads the HOME (POSIX) / USERPROFILE (Windows) env var first,
+// so overriding them here redirects every homedir()-derived path — e.g.
+// activity-log.ts's emit() — into a throwaway temp dir. Without this, fixture
+// events (the `myapp` kshetra, `proj-42` task) leaked into the real log.
+const fakeHome = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), 'shreni-test-home-'));
+process.env.HOME = fakeHome;
+process.env.USERPROFILE = fakeHome;
+//# sourceMappingURL=test-setup.js.map

package/dist/test-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.js","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":";;AAAA,2BAAiC;AACjC,2BAA4B;AAC5B,+BAA4B;AAE5B,6EAA6E;AAC7E,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,wEAAwE;AACxE,8EAA8E;AAC9E,yEAAyE;AACzE,MAAM,QAAQ,GAAG,IAAA,gBAAW,EAAC,IAAA,WAAI,EAAC,IAAA,WAAM,GAAE,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAClE,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC;AAC5B,OAAO,CAAC,GAAG,CAAC,WAAW,GAAG,QAAQ,CAAC"}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "shreni",
+  "version": "0.1.0",
+  "description": "Local-first, bring-your-own-model agent harness that turns a backlog into reviewed, merged code",
+  "main": "dist/index.js",
+  "bin": {
+    "shreni": "dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "pnpm build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "ARCHITECTURE.md",
+    "LICENSE",
+    "TRADEMARK.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TeakWood/Shreni.git"
+  },
+  "keywords": [
+    "ai-agents",
+    "autonomous-agents",
+    "coding-agent",
+    "code-review",
+    "orchestrator",
+    "agent-harness",
+    "local-first",
+    "bring-your-own-model"
+  ],
+  "author": "TeakWood <teakwood.dev@gmail.com>",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "packageManager": "pnpm@10.12.1",
+  "engines": {
+    "node": ">=20",
+    "npm": "please-use-pnpm",
+    "yarn": "please-use-pnpm"
+  },
+  "bugs": {
+    "url": "https://github.com/TeakWood/Shreni/issues"
+  },
+  "homepage": "https://github.com/TeakWood/Shreni#readme",
+  "devDependencies": {
+    "@types/node": "^25.9.2",
+    "@vitest/coverage-v8": "^4.1.8",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.102.0",
+    "@fastify/static": "^9.1.3",
+    "@fastify/websocket": "^11.2.0",
+    "@types/js-yaml": "^4.0.9",
+    "fastify": "^5.8.5",
+    "js-yaml": "^4.2.0",
+    "zod": "^4.4.3"
+  }
+}