instar 1.3.726 → 1.3.727

package/dist/permissions/TestWorkspacePrincipalSource.d.ts

@@ -0,0 +1,133 @@
+/**
+ * TestWorkspacePrincipalSource — the sanctioned, workspace-scoped principal source
+ * for the Slack live-test scenario cast (roadmap 0.3 entry condition).
+ *
+ * WHY THIS EXISTS (the 2026-07-01 lesson): the June scenario drives seeded the
+ * five-seat test cast into the production user registry (`users.json`). The
+ * silent-loss registry rebuild removed them, and the fixture-identity guard
+ * ("Test Identity Never Enters Production State", silent-loss-refusal-conservation
+ * §2.D) now — correctly — refuses to let them back in. Principal resolution for
+ * the live-test workspace therefore needs a home that is NOT the production
+ * registry. This module is that home.
+ *
+ * THE PARTITION INVARIANT (the load-bearing design decision):
+ *   - The production registry REFUSES fixture identities (the existing guard,
+ *     untouched by this module).
+ *   - This source ACCEPTS ONLY fixture identities — every cast entry's
+ *     slackUserId must match the SAME single matcher the production guard uses
+ *     (`matchesTestIdentityToken` from `users/testIdentityMarkers.ts`). A
+ *     non-fixture UID is refused at load, loudly.
+ *   By construction an identity can live in exactly one of the two stores —
+ *   a real employee's UID can never be smuggled into the cast to gain a role
+ *   outside the audited registration path, and standing up a NEW test cast
+ *   structurally forces the fixture-marker list to be updated first (which is
+ *   what keeps the production guard aware of the new fixtures). The single
+ *   matcher can never drift into two lists.
+ *
+ * THE SELF-DECLARATION MARKER (fail-closed to ignoring the cast): the config
+ * object MUST self-declare `testWorkspace: true`. Without that marker the source
+ * refuses to load a SINGLE principal — it disables itself, emits ONE loud log
+ * line, and every lookup returns null (production resolution is byte-identical to
+ * having no cast at all). The marker exists so a cast config can never be
+ * activated by accident: sanctioning a live-test workspace is a deliberate,
+ * self-evident opt-in, never an implicit side effect of the block existing.
+ *
+ * SCOPING (fail-closed): the cast resolves ONLY while the Slack adapter's
+ * VERIFIED connected team id (captured from Slack's own `auth.test` response at
+ * adapter start — never from config alone) equals the configured test
+ * `workspaceId`. Before verification, on verification failure, or when the
+ * adapter is connected to any other workspace, every lookup returns null and
+ * the resolver falls through to its existing safe default (unregistered guest).
+ *
+ * READ-ONLY BY DESIGN: this source never writes anything — not users.json, not
+ * a state file. It is consulted ONLY by the permission gate's principal
+ * resolver (production-registry-first via {@link ChainedUserLookup}); it is
+ * invisible to UserManager, sender auth (`authorizedUserIds`), cross-machine
+ * replication, and every other identity surface.
+ *
+ * Note on imports: `testIdentityMarkers.ts` is dependency-light (node builtins +
+ * a type-only core import), so reusing its matcher keeps the permission module
+ * free of runtime core dependencies — and keeps ONE fixture matcher, not two.
+ *
+ * Design: docs/specs/SLACK-ORG-INTEGRATION-SPEC.md §6.2.1;
+ * runbook: docs/specs/SLACK-ORG-TEST-WORKSPACE-RUNBOOK.md.
+ */
+import type { ResolvedUserRecord, UserLookup } from './SlackPrincipalResolver.js';
+/** One seat of the live-test scenario cast (configured in the Slack config block). */
+export interface TestCastEntry {
+    /** The seat's REAL Slack user id in the live-test workspace (must be a fixture-marker id). */
+    slackUserId: string;
+    /** Display name for conversational messages — never a basis for authority. */
+    name?: string;
+    /** The org role this seat plays (owner / admin / member / contributor / …). */
+    orgRole: string;
+}
+/** Why a configured cast entry was refused at load. */
+export interface RejectedCastEntry {
+    slackUserId: string;
+    reason: 'missing-slack-user-id' | 'not-a-fixture-identity' | 'invalid-role' | 'duplicate' | 'cast-cap-exceeded';
+}
+/**
+ * Hard ceiling on cast seats. The scenario cast is five seats today; the cap
+ * exists so the test-cast path can never quietly become a shadow user registry.
+ */
+export declare const MAX_TEST_CAST_SEATS = 12;
+export interface TestWorkspacePrincipalSourceOpts {
+    /** The sanctioned live-test workspace/team id (T…) this cast is scoped to. */
+    workspaceId: string;
+    /**
+     * The REQUIRED self-declaration marker. The source refuses to load ANY
+     * principal unless this is exactly `true` — fail-closed to ignoring the cast
+     * (one loud log line, never a crash, never a production-registry effect).
+     */
+    testWorkspace: boolean;
+    /** The configured cast seats. Invalid entries are refused (see {@link RejectedCastEntry}). */
+    principals: TestCastEntry[];
+    /**
+     * Supplier of the adapter's VERIFIED connected team id (from `auth.test`).
+     * Returning null/undefined (not yet verified, verification failed) keeps the
+     * source inert — fail-closed to the resolver's unregistered-guest default.
+     */
+    getVerifiedWorkspaceId: () => string | null | undefined;
+}
+/** Why the whole source was disabled at construction (loads zero principals). */
+export type TestCastDisabledReason = 'missing-testWorkspace-marker';
+export declare class TestWorkspacePrincipalSource implements UserLookup {
+    private readonly bySlackId;
+    private readonly workspaceId;
+    private readonly getVerifiedWorkspaceId;
+    /** Entries refused at load (surfaced loudly by the wiring site). */
+    readonly rejected: RejectedCastEntry[];
+    /**
+     * True when the whole source refused to load (the self-declaration marker was
+     * absent). A disabled source holds ZERO principals and resolves everything to
+     * null — production resolution is byte-identical to having no cast configured.
+     */
+    readonly disabled: boolean;
+    /** Why the source disabled itself (only set when {@link disabled} is true). */
+    readonly disabledReason?: TestCastDisabledReason;
+    constructor(opts: TestWorkspacePrincipalSourceOpts);
+    /** Number of admitted cast seats. */
+    get size(): number;
+    /**
+     * Resolve a cast seat — ONLY while the verified connected workspace equals the
+     * sanctioned test workspace. Any uncertainty (no verified id yet, supplier
+     * throw, mismatch) resolves null: fail-closed to unregistered guest.
+     */
+    resolveFromSlackUserId(slackUserId: string): ResolvedUserRecord | null;
+}
+/**
+ * ChainedUserLookup — production-registry-first principal resolution.
+ *
+ * Sources are consulted in order; the first non-null record wins. The wiring
+ * site puts the production registry FIRST, so a genuinely registered user can
+ * never be shadowed or role-escalated by a cast entry, and the cast is only
+ * ever a fallback for identities the production registry does not know.
+ * A throwing source is skipped (resolution must never break the message path).
+ */
+export declare class ChainedUserLookup implements UserLookup {
+    private readonly sources;
+    constructor(sources: UserLookup[]);
+    resolveFromSlackUserId(slackUserId: string): ResolvedUserRecord | null;
+}
+//# sourceMappingURL=TestWorkspacePrincipalSource.d.ts.map

package/dist/permissions/TestWorkspacePrincipalSource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestWorkspacePrincipalSource.d.ts","sourceRoot":"","sources":["../../src/permissions/TestWorkspacePrincipalSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAElF,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EACF,uBAAuB,GACvB,wBAAwB,GACxB,cAAc,GACd,WAAW,GACX,mBAAmB,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,MAAM,WAAW,gCAAgC;IAC/C,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,8FAA8F;IAC9F,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;OAIG;IACH,sBAAsB,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACzD;AAED,iFAAiF;AACjF,MAAM,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AAEpE,qBAAa,4BAA6B,YAAW,UAAU;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAkC;IACzE,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,EAAE,CAAM;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAS;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,CAAC,EAAE,sBAAsB,CAAC;gBAErC,IAAI,EAAE,gCAAgC;IA8DlD,qCAAqC;IACrC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;CAcvE;AAED;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,UAAU,EAAE;IAElD,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;CAYvE"}

package/dist/permissions/TestWorkspacePrincipalSource.js

@@ -0,0 +1,189 @@
+/**
+ * TestWorkspacePrincipalSource — the sanctioned, workspace-scoped principal source
+ * for the Slack live-test scenario cast (roadmap 0.3 entry condition).
+ *
+ * WHY THIS EXISTS (the 2026-07-01 lesson): the June scenario drives seeded the
+ * five-seat test cast into the production user registry (`users.json`). The
+ * silent-loss registry rebuild removed them, and the fixture-identity guard
+ * ("Test Identity Never Enters Production State", silent-loss-refusal-conservation
+ * §2.D) now — correctly — refuses to let them back in. Principal resolution for
+ * the live-test workspace therefore needs a home that is NOT the production
+ * registry. This module is that home.
+ *
+ * THE PARTITION INVARIANT (the load-bearing design decision):
+ *   - The production registry REFUSES fixture identities (the existing guard,
+ *     untouched by this module).
+ *   - This source ACCEPTS ONLY fixture identities — every cast entry's
+ *     slackUserId must match the SAME single matcher the production guard uses
+ *     (`matchesTestIdentityToken` from `users/testIdentityMarkers.ts`). A
+ *     non-fixture UID is refused at load, loudly.
+ *   By construction an identity can live in exactly one of the two stores —
+ *   a real employee's UID can never be smuggled into the cast to gain a role
+ *   outside the audited registration path, and standing up a NEW test cast
+ *   structurally forces the fixture-marker list to be updated first (which is
+ *   what keeps the production guard aware of the new fixtures). The single
+ *   matcher can never drift into two lists.
+ *
+ * THE SELF-DECLARATION MARKER (fail-closed to ignoring the cast): the config
+ * object MUST self-declare `testWorkspace: true`. Without that marker the source
+ * refuses to load a SINGLE principal — it disables itself, emits ONE loud log
+ * line, and every lookup returns null (production resolution is byte-identical to
+ * having no cast at all). The marker exists so a cast config can never be
+ * activated by accident: sanctioning a live-test workspace is a deliberate,
+ * self-evident opt-in, never an implicit side effect of the block existing.
+ *
+ * SCOPING (fail-closed): the cast resolves ONLY while the Slack adapter's
+ * VERIFIED connected team id (captured from Slack's own `auth.test` response at
+ * adapter start — never from config alone) equals the configured test
+ * `workspaceId`. Before verification, on verification failure, or when the
+ * adapter is connected to any other workspace, every lookup returns null and
+ * the resolver falls through to its existing safe default (unregistered guest).
+ *
+ * READ-ONLY BY DESIGN: this source never writes anything — not users.json, not
+ * a state file. It is consulted ONLY by the permission gate's principal
+ * resolver (production-registry-first via {@link ChainedUserLookup}); it is
+ * invisible to UserManager, sender auth (`authorizedUserIds`), cross-machine
+ * replication, and every other identity surface.
+ *
+ * Note on imports: `testIdentityMarkers.ts` is dependency-light (node builtins +
+ * a type-only core import), so reusing its matcher keeps the permission module
+ * free of runtime core dependencies — and keeps ONE fixture matcher, not two.
+ *
+ * Design: docs/specs/SLACK-ORG-INTEGRATION-SPEC.md §6.2.1;
+ * runbook: docs/specs/SLACK-ORG-TEST-WORKSPACE-RUNBOOK.md.
+ */
+import { matchesTestIdentityToken } from '../users/testIdentityMarkers.js';
+import { ORG_ROLES } from './types.js';
+/**
+ * Hard ceiling on cast seats. The scenario cast is five seats today; the cap
+ * exists so the test-cast path can never quietly become a shadow user registry.
+ */
+export const MAX_TEST_CAST_SEATS = 12;
+export class TestWorkspacePrincipalSource {
+    bySlackId = new Map();
+    workspaceId;
+    getVerifiedWorkspaceId;
+    /** Entries refused at load (surfaced loudly by the wiring site). */
+    rejected = [];
+    /**
+     * True when the whole source refused to load (the self-declaration marker was
+     * absent). A disabled source holds ZERO principals and resolves everything to
+     * null — production resolution is byte-identical to having no cast configured.
+     */
+    disabled = false;
+    /** Why the source disabled itself (only set when {@link disabled} is true). */
+    disabledReason;
+    constructor(opts) {
+        if (!opts.workspaceId || typeof opts.workspaceId !== 'string' || !opts.workspaceId.trim()) {
+            throw new Error('TestWorkspacePrincipalSource requires a non-empty workspaceId (the sanctioned live-test workspace)');
+        }
+        // Stored TRIMMED (second-pass review note): Slack's own `team_id` never
+        // carries whitespace, so a config value with a stray space would otherwise
+        // make the scope equality permanently false — an inert cast (fail-closed,
+        // but a silent config foot-gun the boot log alone would have to catch).
+        this.workspaceId = opts.workspaceId.trim();
+        this.getVerifiedWorkspaceId = opts.getVerifiedWorkspaceId;
+        // THE SELF-DECLARATION GATE (fail-closed): without an explicit
+        // `testWorkspace: true` the cast is IGNORED entirely — zero principals
+        // loaded, one loud line, no throw, no production impact. The loud line lives
+        // HERE (not only at the wiring site) so the fail-closed guarantee holds for
+        // EVERY caller — Structure > Willpower.
+        if (opts.testWorkspace !== true) {
+            this.disabled = true;
+            this.disabledReason = 'missing-testWorkspace-marker';
+            console.warn(`[slack] TestWorkspacePrincipalSource IGNORED for workspace ${this.workspaceId} — the testCast config is ` +
+                `missing its required "testWorkspace: true" self-declaration. Loading ZERO cast principals (fail-closed; the ` +
+                `production user registry is unaffected). Add "testWorkspace": true to sanction the live-test cast.`);
+            return; // no principals admitted
+        }
+        for (const entry of opts.principals ?? []) {
+            const slackUserId = typeof entry?.slackUserId === 'string' ? entry.slackUserId.trim() : '';
+            if (!slackUserId) {
+                this.rejected.push({ slackUserId: String(entry?.slackUserId ?? ''), reason: 'missing-slack-user-id' });
+                continue;
+            }
+            // THE PARTITION INVARIANT: only fixture-marker identities are admitted.
+            // Same single matcher as the production guard — never a second list.
+            if (!matchesTestIdentityToken(slackUserId)) {
+                this.rejected.push({ slackUserId, reason: 'not-a-fixture-identity' });
+                continue;
+            }
+            if (!entry.orgRole || !ORG_ROLES.includes(entry.orgRole)) {
+                this.rejected.push({ slackUserId, reason: 'invalid-role' });
+                continue;
+            }
+            if (this.bySlackId.has(slackUserId)) {
+                this.rejected.push({ slackUserId, reason: 'duplicate' });
+                continue;
+            }
+            if (this.bySlackId.size >= MAX_TEST_CAST_SEATS) {
+                this.rejected.push({ slackUserId, reason: 'cast-cap-exceeded' });
+                continue;
+            }
+            this.bySlackId.set(slackUserId, {
+                // Namespaced id so a cast principal is visibly a test seat in every
+                // ledger row / audit surface it appears in.
+                id: `test-cast:${slackUserId}`,
+                name: entry.name?.trim() || slackUserId,
+                permissions: [entry.orgRole],
+                orgRole: entry.orgRole,
+            });
+        }
+    }
+    /** Number of admitted cast seats. */
+    get size() {
+        return this.bySlackId.size;
+    }
+    /**
+     * Resolve a cast seat — ONLY while the verified connected workspace equals the
+     * sanctioned test workspace. Any uncertainty (no verified id yet, supplier
+     * throw, mismatch) resolves null: fail-closed to unregistered guest.
+     */
+    resolveFromSlackUserId(slackUserId) {
+        // A disabled source (missing marker) holds no principals — this is redundant
+        // with the empty map but makes the fail-closed contract explicit.
+        if (this.disabled)
+            return null;
+        let verified;
+        try {
+            verified = this.getVerifiedWorkspaceId();
+        }
+        catch {
+            // Fail-closed: an errored verification supplier keeps the cast inert.
+            return null;
+        }
+        if (!verified || verified !== this.workspaceId)
+            return null;
+        return this.bySlackId.get(slackUserId) ?? null;
+    }
+}
+/**
+ * ChainedUserLookup — production-registry-first principal resolution.
+ *
+ * Sources are consulted in order; the first non-null record wins. The wiring
+ * site puts the production registry FIRST, so a genuinely registered user can
+ * never be shadowed or role-escalated by a cast entry, and the cast is only
+ * ever a fallback for identities the production registry does not know.
+ * A throwing source is skipped (resolution must never break the message path).
+ */
+export class ChainedUserLookup {
+    sources;
+    constructor(sources) {
+        this.sources = sources;
+    }
+    resolveFromSlackUserId(slackUserId) {
+        for (const source of this.sources) {
+            try {
+                const record = source.resolveFromSlackUserId(slackUserId);
+                if (record)
+                    return record;
+            }
+            catch {
+                // A faulty source must never break principal resolution — fall through
+                // to the next source (ultimately the unregistered-guest default).
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=TestWorkspacePrincipalSource.js.map

package/dist/permissions/TestWorkspacePrincipalSource.js.map

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

package/dist/permissions/index.d.ts

@@ -16,4 +16,5 @@ export * from './MandateBackedGrantStore.js';
 export * from './SlackPrincipalResolver.js';
 export * from './SlackPermissionObserver.js';
 export * from './SlackUserRegistry.js';
+export * from './TestWorkspacePrincipalSource.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/permissions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC"}

package/dist/permissions/index.js

@@ -16,4 +16,5 @@ export * from './MandateBackedGrantStore.js';
 export * from './SlackPrincipalResolver.js';
 export * from './SlackPermissionObserver.js';
 export * from './SlackUserRegistry.js';
+export * from './TestWorkspacePrincipalSource.js';
 //# sourceMappingURL=index.js.map

package/dist/permissions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/permissions/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,wBAAwB,CAAC;AACvC,cAAc,mCAAmC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.726",
+  "version": "1.3.727",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-03T01:15:56.453Z",
-  "instarVersion": "1.3.726",
+  "generatedAt": "2026-07-03T01:19:27.750Z",
+  "instarVersion": "1.3.727",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.727.md

@@ -0,0 +1,143 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`AgentWorktreeReaper.start()` scheduled ONLY a 24h `setInterval` — no initial
+pass. Agent servers restart far more often than daily (auto-updates, sleep/wake
+supervisor bounces), so the interval timer reset on every restart and an
+**enabled + armed** reaper never ran a single pass. Measured live on 2026-07-02:
+86 worktrees / 25GB accumulated on a machine with `enabled: true, dryRun: false`
+and `lastPassAt: 0` — the feature was on and structurally inert (root cause of
+that day's fseventsd/reboot resource incident).
+
+The fix:
+
+- New `initialPassDelayMs` config (default 15 min; `<= 0` disables — the exact
+  legacy behavior as a no-release rollback lever) on
+  `monitoring.agentWorktreeReaper`.
+- `start()` now schedules a ONE-TIME initial pass after that delay (unref'd
+  timer, cleared by `stop()`), then the unchanged 24h cadence. The delay keeps
+  the pass off the busy post-boot window.
+- The pass runs through the same `reap()` as always: same KEEP gates (in-use /
+  dirty / unmerged / detached), same dry-run gating, same `maxReapsPerPass`
+  blast-radius cap, same per-path reclaim-failure breaker. Nothing about WHAT
+  may be deleted changed — only WHEN passes run.
+- `GET /worktrees/agent-reaper` snapshot additively reports
+  `initialPassPending`.
+- CLAUDE.md template + PostUpdateMigrator addendum so deployed agents learn the
+  new behavior (idempotent, content-sniffed on `initialPassDelayMs`).
+
+Fixes the roadmap-0.3 blocker found in the Slack permission-gate false-positive
+review (`docs/audits/slack-permission-fp-review-2026-07.md`, row 29): after the
+2026-07-01 silent-loss registry rebuild, the Slack live-test scenario cast could no
+longer resolve, so every Slack sender — including the workspace owner — resolved as an
+unregistered guest. Root cause: the gate derives roles from the production user registry
+(`users.json`), the rebuild removed the five Slack test-cast principals, and the
+fixture-identity guard (correctly) refuses to let test identities back into the
+production registry.
+
+The fix is a SEPARATE, test-workspace-scoped principal source rather than a registry
+edit:
+
+- **New `TestWorkspacePrincipalSource` + `ChainedUserLookup`** (`src/permissions/`).
+  The gate's `SlackPrincipalResolver` now reads production-registry-FIRST, then the
+  cast as a fallback. A production-registered user can never be shadowed or
+  role-escalated by a cast entry.
+- **Config-carried cast** — `permissionGate.testCast` in the Slack messaging config
+  (`{ testWorkspace, workspaceId, principals[] }`). It lives beside the workspace
+  tokens, so a `users.json` rebuild can never silently drop it again.
+- **Code-enforced workspace scoping** — the cast resolves ONLY while the adapter's
+  VERIFIED connected team id (captured from Slack's own `auth.test` at start, exposed
+  via `SlackAdapter.getConnectedTeamId()`) EXACTLY equals `workspaceId`. Any other
+  workspace → the source is structurally invisible (production behavior byte-identical
+  to no cast). An unlisted uid in the test workspace → today's unregistered-guest default.
+- **Partition invariant** — every cast `slackUserId` must match the SAME fixture-marker
+  matcher (`users/testIdentityMarkers.ts`) the production guard uses to refuse fixtures;
+  a non-fixture id is refused at load. One identity, two disjoint homes.
+- **Fail-closed self-declaration** — the block must set `testWorkspace: true`; without
+  it the whole cast is ignored (zero principals, one loud log line, no production
+  effect). A cast can never be activated by accident.
+- **Authority scope (KYP)** — the source feeds permission-gate role resolution ONLY. It
+  takes no state dir and has no write surface, so it cannot create user-registry
+  entries, cannot feed operator binding, and cannot affect message authorization /
+  sender validation.
+
+The runbook (`docs/specs/SLACK-ORG-TEST-WORKSPACE-RUNBOOK.md`) is patched: the old
+"seed the cast in users.json" step is replaced with the `testCast` config block plus a
+re-provision checklist so a registry rebuild can't silently lose principal resolution
+again. Dark by default — nothing activates without an explicit `testCast` block.
+
+## What to Tell Your User
+
+<!-- audience: user, maturity: stable -->
+
+If you switched on the stale-worktree auto-cleaner, it now genuinely runs: one
+cleaning pass about 15 minutes after each server start, then daily as designed.
+Previously a quirk meant frequent server restarts kept pushing its first run
+into the future forever, so leftover work folders could quietly pile up into
+tens of gigabytes even with the cleaner enabled. Its safety rules are untouched:
+it still only removes folders whose work is fully merged and saved, still does
+dry-run first, and it stays entirely off unless you enabled it.
+
+- **Slack permission demo is more robust**: the test harness that proves the Slack
+  "who's allowed to do what" feature now keeps its demo cast in a safe place that a
+  routine cleanup of your real people-list can't wipe out. This is behind-the-scenes
+  test infrastructure — nothing changes in how I work for you day to day, and the
+  pretend demo roles are locked to the throwaway test workspace so they can never leak
+  into a real one.
+
+## Summary of New Capabilities
+
+- The stale-worktree reaper actually fires on real deployments: a one-time
+  cleaning pass ~15 minutes after boot (tunable/disableable via
+  `monitoring.agentWorktreeReaper.initialPassDelayMs`), unchanged daily cadence
+  thereafter, and `initialPassPending` visibility on the existing report route.
+
+| Capability | How to Use |
+|-----------|-----------|
+| Test-workspace-scoped Slack principal cast | Add a `testCast` block (with `testWorkspace: true`, `workspaceId`, `principals`) under the Slack `permissionGate` config — dark unless configured |
+
+## Evidence
+
+- `tests/unit/agent-worktree-reaper.test.ts`: 47/47 green — 7 new tests (initial
+  pass fires exactly once at the configured delay and before the interval;
+  respects dry-run; disabled reaper sets no timers; `<= 0` restores
+  interval-only; `stop()` cancels the pending pass; 24h cadence unchanged after
+  the initial pass; snapshot reports `initialPassPending` honestly).
+- Live incident data (2026-07-02, topic 30379): reaper enabled+armed with 25
+  reap-eligible worktrees and `lastPassAt: 0`; server uptime history shows no
+  24h-continuous window for weeks.
+
+Root cause is a live datapoint captured in `docs/audits/slack-permission-fp-review-2026-07.md`:
+row 29 (2026-07-02 18:15:19, the only organic decision row) shows the workspace OWNER
+seat's Slack UID resolving as `role: guest, registered: false` — the same UID that
+resolved as `role: owner, registered: true` in every June scenario row, because the
+2026-07-01 rebuild removed the cast from `users.json`.
+
+The fix is verified by `tests/unit/slack-test-workspace-principal-source.test.ts` (22
+tests, all passing), which exercises BOTH sides of every boundary:
+
+- matching workspace + listed uid → registered role; matching workspace + unlisted uid
+  → guest.
+- non-matching workspace + listed uid → source invisible, and the resolved principal is
+  asserted EQUAL to the no-cast baseline (the scoping proof that roles can't leak into a
+  production workspace).
+- missing `testWorkspace: true` → source disabled, zero seats, loud log line, and
+  byte-identical to no cast.
+- non-fixture uid refused at load; cast cap enforced; production-registry-first
+  precedence; a throwing source skipped.
+- authority-scope assertions: the source exposes only the read contract (no
+  write/registry/operator methods) and takes no state dir.
+
+`tests/integration/slack-testcast-principal-pipeline.test.ts` (5 tests, all passing)
+additionally drives the EXACT server.ts composition through the real inbound chokepoint
+(`SlackAdapter._handleMessage`) and asserts the durable decision-ledger rows: the owner
+seat resolves `owner, registered:true` through the live path (the row-29 regression),
+the same seat is an unregistered guest when connected to any other workspace or before
+`auth.test` verifies the connection, an unlisted uid stays a guest, and a production
+record beats the cast for the same uid.
+
+`npx tsc --noEmit` exits 0.