@dsh-cc/subagent-resume-pins 0.5.0

package/lib/plugin.js

@@ -0,0 +1,354 @@
+/**
+ * The resume-pins cordis plugin (plan §4.6-§4.10): one `PinStore`, the
+ * `subagents-resume` settings namespace, the `tools/pre-execute` resume gate,
+ * the `tools/post-execute` notice/annotation listeners, and the
+ * `agent/request` runtime overlay.
+ *
+ * Zero-op when unmounted: pins are simply unread and behavior is today's
+ * legacy behavior. When mounted, only pinned children are affected — a
+ * missing pin is a legacy/foreign child (pass-through), and a same-epoch
+ * followup to a live Activation is untouched.
+ *
+ * Durability ordering: every deny persists `resume.state='blocked'` (reason)
+ * through the shared store — an atomic disk rewrite plus synchronous cache
+ * publication — BEFORE the deny decision returns, so the overlay listener
+ * fails any unmonitored resume of that child visibly. An all-passing gate
+ * clears the stored blocked state. Gate and overlay share the ONE store
+ * exposed as the `resumePinStore` service (spawn capture prefers it too).
+ *
+ * @module @dsh-cc/subagent-resume-pins/plugin
+ */
+import { existsSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { realpathSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import z from '@deepseek-ai/schemastery';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { loadAgentsDir, discoverBundledAgents } from '@dsh-cc/claude-code-agents';
+import { resolveDetailedAlias } from '@dsh-cc/model-aliases';
+import { evaluateGate } from "./gate.js";
+import { PinBlockedError, applyPinOverlay } from "./overlay.js";
+import { definitionFingerprint } from "./fingerprint.js";
+import { RESUME_POLICY_NAMESPACE, readResumePolicy, } from "./policy.js";
+import { serializePerKey, ExecutionNoticeBus } from "./serialize.js";
+import { PinStore } from "./store.js";
+/**
+ * The settings section schema (plan §4.9): one constrained enum field per
+ * knob with explicit defaults, mirroring how `cc-model-aliases` registers its
+ * schema — invalid spellings are rejected at write time by the settings
+ * service; `readResumePolicy` keeps tolerating hand-edited documents.
+ */
+export const ResumePolicySchema = z.object({
+    onUnavailableModel: z.union([z.const('block'), z.const('route-current')]).default('block'),
+    onDefinitionChanged: z.union([z.const('resume-with-notice'), z.const('block')]).default('resume-with-notice'),
+    onWorkspaceChanged: z.union([z.const('resume-with-notice'), z.const('block')]).default('resume-with-notice'),
+});
+/** Cordis plugin id. */
+export const name = 'cc-subagent-resume-pins';
+/** The service key the spawn capture resolves to share the store. */
+export const RESUME_PIN_STORE = 'resumePinStore';
+/** The spawn-time git identity probe timeout (matches the capture probe). */
+const GIT_PROBE_TIMEOUT_MS = 2_000;
+/**
+ * Normalize one `git rev-parse` output to a cwd-anchored absolute path (git
+ * prints repository-relative values like `.git`), realpath'ed when cheap so
+ * the same repo reached through different paths compares equal. The `'unknown'`
+ * sentinel passes through. Residual limit: two DIFFERENT repos initialized
+ * sequentially at the same path normalize to the same path string — the
+ * worktree↔standalone and cwd-move cases ARE detected; same-path replacement
+ * of a standalone repo by another standalone repo is not.
+ */
+function normalizeGitPath(cwd, value) {
+    if (value === 'unknown' || value.length === 0)
+        return 'unknown';
+    const absolute = isAbsolute(value) ? value : join(cwd, value);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** Best-effort current git identity of one cwd ('unknown' sentinels on failure). */
+function gitIdentity(cwd) {
+    try {
+        const result = spawnSync('git', ['-C', cwd, 'rev-parse', '--git-dir', '--git-common-dir', '--abbrev-ref', 'HEAD'], { timeout: GIT_PROBE_TIMEOUT_MS, encoding: 'utf8' });
+        const [gitDir, gitCommonDir, branch] = (result.stdout ?? '').trim().split('\n');
+        if (result.status !== 0 || gitDir === undefined || gitCommonDir === undefined || branch === undefined) {
+            return { gitDir: 'unknown', gitCommonDir: 'unknown', branch: 'unknown' };
+        }
+        return {
+            gitDir: normalizeGitPath(cwd, gitDir),
+            gitCommonDir: normalizeGitPath(cwd, gitCommonDir),
+            branch,
+        };
+    }
+    catch {
+        return { gitDir: 'unknown', gitCommonDir: 'unknown', branch: 'unknown' };
+    }
+}
+/**
+ * Re-fingerprint a named definition OUTSIDE the registry cache (§4.4).
+ * Bundled pins re-fingerprint from the CURRENT in-package bundled registry.
+ * Project/user pins re-read the EXACT recorded `baseDir`+`filename`, falling
+ * back to an `agentType` lookup only when the recorded file is gone (that is
+ * the changed-by-replacement class). `'missing'` for a gone/unreadable
+ * definition; `null` when no current information exists (a pin without a
+ * file location).
+ */
+export async function refingerprintDefinition(pin) {
+    const definition = pin.definition;
+    if (definition.kind !== 'named')
+        return null;
+    if (definition.source === 'bundled') {
+        try {
+            const found = discoverBundledAgents().find(def => def.agentType === definition.agentType);
+            return found === undefined ? 'missing' : definitionFingerprint(found);
+        }
+        catch {
+            return 'missing';
+        }
+    }
+    if (definition.baseDir === undefined || definition.filename === undefined)
+        return null;
+    try {
+        const defs = await loadAgentsDir(definition.baseDir, definition.source);
+        const found = defs.find(def => def.filename === definition.filename)
+            ?? defs.find(def => def.agentType === definition.agentType);
+        return found === undefined ? 'missing' : definitionFingerprint(found);
+    }
+    catch {
+        return 'missing';
+    }
+}
+/** The text of one tool result's content blocks (for annotation matching). */
+function resultText(result) {
+    return result.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('');
+}
+/**
+ * Mount the resume-pin gate, overlay, notices, and policy namespace.
+ * @param ctx - the plug context.
+ * @param config - pins root (or an injected store).
+ */
+export function apply(ctx, config) {
+    const store = config.store ?? new PinStore(config.pinsRoot);
+    ctx.provide(RESUME_PIN_STORE, store);
+    // §4.9: register the policy namespace when a settings provider is mounted;
+    // read LIVE on every gate evaluation (a flip is authoritative immediately).
+    const settings = ctx.get('settings');
+    const scope = settings?.register?.(RESUME_POLICY_NAMESPACE, ResumePolicySchema);
+    const policy = () => readResumePolicy(scope?.get?.());
+    // Pre→post communication: gate-computed notices for a child's NEXT
+    // send_message result, keyed by the tool execution identity (`exec.token`,
+    // the registry-assigned opaque call identity present on BOTH the pre- and
+    // post-execute payloads) so a failing send can never leak its notice into a
+    // later call. Per-child promise chains serialize gate evaluation +
+    // persistence + followup admission, so concurrent sends to one cold child
+    // cannot interleave their decisions or cross-deliver notices.
+    const pendingNotices = new ExecutionNoticeBus();
+    const childLocks = new Map();
+    /**
+     * Lookup-level read: an unsafe childId (harness session ids are
+     * unconstrained branded strings) is a validation failure at LOOKUP level →
+     * passthrough `undefined`, exactly like an absent pin. Only WRITE paths
+     * reject unsafe ids.
+     */
+    const safeRead = (childId) => {
+        try {
+            return store.read(childId);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const readPin = safeRead;
+    /**
+     * Persist a deny to the pin BEFORE the decision returns (§4.6 ordering).
+     * Propagates write failure: the caller keeps denying with a reason that
+     * names the persistence failure — a pending deny is never downgraded to a
+     * followup just because the durable marker could not be written.
+     */
+    const persistBlocked = (pin, decision) => {
+        if (decision.action !== 'deny')
+            return;
+        store.update(pin.childId, draft => {
+            draft.resume = { state: 'blocked', reason: decision.reason };
+            draft.lastNotice = decision.reason;
+        });
+    };
+    /**
+     * Persist a passing evaluation: clear blocked state, cache overlay/notices.
+     * Propagates write failure — a pending PASS/route-current must not followup
+     * until the required durable state is published; the caller denies with
+     * `STORE_WRITE_FAILURE` instead.
+     */
+    const persistPass = (pin, decision) => {
+        store.update(pin.childId, draft => {
+            draft.resume = {
+                state: 'ok',
+                ...(decision.overlay !== undefined ? { overlay: decision.overlay } : {}),
+            };
+            draft.lastNotice = decision.notices.length > 0 ? decision.notices.join('\n') : undefined;
+        });
+    };
+    const gateEnv = async (pin, callingAgent) => {
+        let sessionExists = false;
+        try {
+            const persistence = ctx.sessionPersistence;
+            if (persistence?.inspect !== undefined) {
+                await persistence.inspect(SessionId(pin.childId));
+                sessionExists = true;
+            }
+        }
+        catch {
+            sessionExists = false;
+        }
+        let restrictableNames = new Set();
+        try {
+            const view = ctx.tools
+                .view?.(callingAgent);
+            restrictableNames = view?.restrictableNames ?? new Set();
+        }
+        catch {
+            restrictableNames = new Set();
+        }
+        // The calling parent's CURRENT route (AgentOptions) — the route-current
+        // fallback overlays onto this, never onto the pinned tuple.
+        const currentRoute = callingAgent?.options;
+        const llm = ctx.get('llm');
+        return {
+            sessionExists,
+            cwdExists: existsSync(pin.workspace.cwd),
+            currentGit: gitIdentity(pin.workspace.cwd),
+            currentDefinitionFingerprint: await refingerprintDefinition(pin),
+            restrictableNames,
+            resolveCallConfig: config => {
+                if (llm?.resolveCallConfig === undefined)
+                    return Promise.reject(new Error('no llm service for the availability preflight'));
+                return llm.resolveCallConfig(config);
+            },
+            resolveDetailed: selector => resolveDetailedAlias(ctx, selector),
+            ...(currentRoute !== undefined ? { currentRoute } : {}),
+        };
+    };
+    // §4.6: the resume gate. Fires on every tool call; acts only on
+    // `send_message` to a PINNED child with no live Activation. Gate
+    // evaluation + persistence + followup admission are serialized per child.
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        if (exec.name !== 'send_message')
+            return next();
+        const target = exec.arguments?.subagent_id;
+        if (typeof target !== 'string' || target.length === 0)
+            return next();
+        return serializePerKey(childLocks, target, async () => {
+            const found = readPin(target);
+            if (found === undefined)
+                return next(); // legacy/foreign child: pass through
+            if ('kind' in found) {
+                return { kind: 'deny', reason: `[PIN_UNREADABLE] resume pin for ${target} is unreadable (${found.reason}); refusing to resume` };
+            }
+            // Same-epoch followup to a live agent: untouched.
+            if (ctx.agents.get(SessionId(target)) !== undefined)
+                return next();
+            const decision = await evaluateGate(found, await gateEnv(found, exec.agent), policy());
+            if (decision.action === 'deny') {
+                try {
+                    persistBlocked(found, decision);
+                }
+                catch (error) {
+                    // Fail closed: the deny stands even when the durable marker could
+                    // not be written; the reason names the persistence failure.
+                    return {
+                        kind: 'deny',
+                        reason: `${decision.reason} (resume pin persistence failed: ${error.message})`,
+                    };
+                }
+                return { kind: 'deny', reason: decision.reason };
+            }
+            // Durability ordering: the pass result (cleared state, overlay cache,
+            // notices) is published synchronously BEFORE the followup is queued —
+            // a store-write failure denies with a store-write-failure code and the
+            // followup never happens.
+            try {
+                persistPass(found, decision);
+            }
+            catch (error) {
+                return {
+                    kind: 'deny',
+                    reason: `[STORE_WRITE_FAILURE] resume pin could not publish the gate result for ${target} (${error.message}); refusing to resume until the durable state is written`,
+                };
+            }
+            if (decision.notices.length > 0) {
+                pendingNotices.publish(exec.token, decision.notices);
+            }
+            return next();
+        });
+    });
+    // §4.7: prefix the gate's notices onto the send_message result; annotate
+    // list_agents for pinned children.
+    ctx.on('tools/post-execute', async (exec, result, next) => {
+        const out = await next();
+        if (out.kind !== 'accept')
+            return out;
+        if (exec.name === 'send_message') {
+            const notices = pendingNotices.take(exec.token);
+            if (notices.length > 0) {
+                return { kind: 'accept', content: [...notices.map(text => ({ type: 'text', text })), ...(out.content ?? [])] };
+            }
+            return out;
+        }
+        if (exec.name === 'list_agents') {
+            const annotations = [];
+            const text = resultText(result);
+            for (const childId of store.ids()) {
+                if (!text.includes(childId))
+                    continue;
+                const pin = readPin(childId);
+                if (pin === undefined)
+                    continue;
+                if ('kind' in pin) {
+                    annotations.push(`[resume-pin] ${childId}: state blocked (pin unreadable)`);
+                    continue;
+                }
+                const current = await refingerprintDefinition(pin);
+                const pinnedFingerprint = pin.definition.kind === 'named' ? pin.definition.fingerprint : undefined;
+                const definitionChanged = current !== null && (pinnedFingerprint === undefined || current !== pinnedFingerprint);
+                const parts = [`state ${pin.resume.state}`];
+                if (definitionChanged)
+                    parts.push('definition changed');
+                if (pin.lastNotice !== undefined)
+                    parts.push(pin.lastNotice);
+                annotations.push(`[resume-pin] ${childId}: ${parts.join('; ')}`);
+            }
+            if (annotations.length > 0) {
+                return { kind: 'accept', content: [...(out.content ?? []), { type: 'text', text: annotations.join('\n') }] };
+            }
+        }
+        return out;
+    });
+    // §4.8: the request-time overlay — every turn of a pinned child, whatever
+    // resumed it. Miss → passthrough; blocked or corrupt → visible failure
+    // (fail-closed: the corrupt pin file IS the durable blocked marker). The
+    // read is read-through: a file deleted or corrupted out-of-band is never
+    // served from the cache.
+    ctx.on('agent/request', async ({ agent }, next) => {
+        const resolved = await next();
+        if (agent === undefined)
+            return resolved;
+        const pin = safeRead(String(agent.id));
+        if (pin === undefined)
+            return resolved;
+        if ('kind' in pin) {
+            throw new PinBlockedError(`resume pin for ${String(agent.id)} is unreadable (${pin.reason}); refusing the request`);
+        }
+        try {
+            return applyPinOverlay(resolved, pin);
+        }
+        catch (error) {
+            if (error instanceof PinBlockedError)
+                throw error;
+            return resolved;
+        }
+    });
+}
+//# sourceMappingURL=plugin.js.map

package/lib/plugin.js.map

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

package/lib/policy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The explicit runtime policy for resume gates (plan §4.9): the
+ * `subagents-resume` settings namespace (the plan's `subagents.resume` —
+ * the settings namespace grammar only accepts kebab-case). Read LIVE on
+ * every gate evaluation: a policy flip is authoritative for the next
+ * evaluation, and a persisted `blocked` state never short-circuits it.
+ *
+ * Every value is an explicit, inspectable choice — there is no silent
+ * substitution anywhere. `WORKSPACE_MISSING`, `PIN_ORPHANED`,
+ * `PINNED_TOOL_UNAVAILABLE`, and `PIN_UNREADABLE` always block regardless of
+ * this policy: no safe fallback exists for them.
+ *
+ * @module @dsh-cc/subagent-resume-pins/policy
+ */
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
+/** The settings namespace carrying the resume policy. */
+export declare const RESUME_POLICY_NAMESPACE: SettingsNamespace;
+/** What happens when the pinned provider/model route is no longer available. */
+export type OnUnavailableModel = 'block' | 'route-current';
+/** What happens when a named definition's fingerprint changed (or is gone). */
+export type OnDefinitionChanged = 'resume-with-notice' | 'block';
+/** What happens when the workspace's canonical repo identity changed. */
+export type OnWorkspaceChanged = 'resume-with-notice' | 'block';
+/** The resolved resume policy consumed by the gate. */
+export interface ResumePolicy {
+    readonly onUnavailableModel: OnUnavailableModel;
+    readonly onDefinitionChanged: OnDefinitionChanged;
+    readonly onWorkspaceChanged: OnWorkspaceChanged;
+}
+/** The defaults every value falls back to; fail-closed on the model knob. */
+export declare const RESUME_POLICY_DEFAULTS: ResumePolicy;
+/**
+ * Resolve the live policy from one raw settings section: unknown fields are
+ * ignored; an invalid value falls back to its default (the section schema and
+ * write-time validation are the first line — this keeps a hand-edited document
+ * from being read as an unintended policy). Absent section → the defaults.
+ * @param raw - the live `subagents-resume` section (any shape).
+ * @returns the resolved policy.
+ */
+export declare function readResumePolicy(raw: unknown): ResumePolicy;
+//# sourceMappingURL=policy.d.ts.map

package/lib/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAElE,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,EAAE,iBAAyD,CAAA;AAE/F,gFAAgF;AAChF,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,eAAe,CAAA;AAE1D,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,OAAO,CAAA;AAEhE,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,GAAG,OAAO,CAAA;AAE/D,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAA;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAA;IACjD,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,CAAA;CAChD;AAED,6EAA6E;AAC7E,eAAO,MAAM,sBAAsB,EAAE,YAIpC,CAAA;AAKD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAU3D"}

package/lib/policy.js

@@ -0,0 +1,45 @@
+/**
+ * The explicit runtime policy for resume gates (plan §4.9): the
+ * `subagents-resume` settings namespace (the plan's `subagents.resume` —
+ * the settings namespace grammar only accepts kebab-case). Read LIVE on
+ * every gate evaluation: a policy flip is authoritative for the next
+ * evaluation, and a persisted `blocked` state never short-circuits it.
+ *
+ * Every value is an explicit, inspectable choice — there is no silent
+ * substitution anywhere. `WORKSPACE_MISSING`, `PIN_ORPHANED`,
+ * `PINNED_TOOL_UNAVAILABLE`, and `PIN_UNREADABLE` always block regardless of
+ * this policy: no safe fallback exists for them.
+ *
+ * @module @dsh-cc/subagent-resume-pins/policy
+ */
+import { settingsNamespace } from '@deepseek-ai/dsh-settings';
+/** The settings namespace carrying the resume policy. */
+export const RESUME_POLICY_NAMESPACE = settingsNamespace('subagents-resume');
+/** The defaults every value falls back to; fail-closed on the model knob. */
+export const RESUME_POLICY_DEFAULTS = {
+    onUnavailableModel: 'block',
+    onDefinitionChanged: 'resume-with-notice',
+    onWorkspaceChanged: 'resume-with-notice',
+};
+const ON_UNAVAILABLE = ['block', 'route-current'];
+const ON_CHANGED = ['resume-with-notice', 'block'];
+/**
+ * Resolve the live policy from one raw settings section: unknown fields are
+ * ignored; an invalid value falls back to its default (the section schema and
+ * write-time validation are the first line — this keeps a hand-edited document
+ * from being read as an unintended policy). Absent section → the defaults.
+ * @param raw - the live `subagents-resume` section (any shape).
+ * @returns the resolved policy.
+ */
+export function readResumePolicy(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return RESUME_POLICY_DEFAULTS;
+    const record = raw;
+    const pick = (value, values, fallback) => typeof value === 'string' && values.includes(value) ? value : fallback;
+    return {
+        onUnavailableModel: pick(record['onUnavailableModel'], ON_UNAVAILABLE, RESUME_POLICY_DEFAULTS.onUnavailableModel),
+        onDefinitionChanged: pick(record['onDefinitionChanged'], ON_CHANGED, RESUME_POLICY_DEFAULTS.onDefinitionChanged),
+        onWorkspaceChanged: pick(record['onWorkspaceChanged'], ON_CHANGED, RESUME_POLICY_DEFAULTS.onWorkspaceChanged),
+    };
+}
+//# sourceMappingURL=policy.js.map

package/lib/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAG7D,yDAAyD;AACzD,MAAM,CAAC,MAAM,uBAAuB,GAAsB,iBAAiB,CAAC,kBAAkB,CAAC,CAAA;AAkB/F,6EAA6E;AAC7E,MAAM,CAAC,MAAM,sBAAsB,GAAiB;IAClD,kBAAkB,EAAE,OAAO;IAC3B,mBAAmB,EAAE,oBAAoB;IACzC,kBAAkB,EAAE,oBAAoB;CACzC,CAAA;AAED,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,eAAe,CAAU,CAAA;AAC1D,MAAM,UAAU,GAAG,CAAC,oBAAoB,EAAE,OAAO,CAAU,CAAA;AAE3D;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,sBAAsB,CAAA;IAC1E,MAAM,MAAM,GAAG,GAA8B,CAAA;IAC7C,MAAM,IAAI,GAAG,CAAmB,KAAc,EAAE,MAAoB,EAAE,QAAW,EAAK,EAAE,CACtF,OAAO,KAAK,KAAK,QAAQ,IAAK,MAA4B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAU,CAAC,CAAC,CAAC,QAAQ,CAAA;IACpG,OAAO;QACL,kBAAkB,EAAE,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,cAAc,EAAE,sBAAsB,CAAC,kBAAkB,CAAC;QACjH,mBAAmB,EAAE,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,EAAE,UAAU,EAAE,sBAAsB,CAAC,mBAAmB,CAAC;QAChH,kBAAkB,EAAE,IAAI,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,UAAU,EAAE,sBAAsB,CAAC,kBAAkB,CAAC;KAC9G,CAAA;AACH,CAAC"}

package/lib/serialize.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Plugin-side concurrency primitives (plan §4.6/§4.7): per-child gate
+ * serialization and execution-token-keyed notice delivery.
+ *
+ * - {@link serializePerKey} runs tasks with the same key strictly in start
+ *   order (a per-key promise chain): concurrent gate evaluations +
+ *   persistence + followup admission for one cold child cannot interleave.
+ *   A failing task propagates its rejection to its own caller only — the
+ *   chain continues for later tasks.
+ * - {@link ExecutionNoticeBus} keys pending gate notices by the tool
+ *   execution identity (`exec.token`, present on both the pre- and
+ *   post-execute payloads), so a failing send can never leak its notice into
+ *   a later call: only the very same execution may take them.
+ *
+ * @module @dsh-cc/subagent-resume-pins/serialize
+ */
+/** Run `task` after any pending same-key task settles; keyed FIFO order. */
+export declare function serializePerKey<T>(locks: Map<string, Promise<unknown>>, key: string, task: () => Promise<T>): Promise<T>;
+/** Pending gate notices keyed by tool execution identity. */
+export declare class ExecutionNoticeBus {
+    private readonly pending;
+    /** Publish the notices a passing gate produced for ONE execution. */
+    publish(token: unknown, notices: readonly string[]): void;
+    /** Take (and clear) the notices published for exactly this execution. */
+    take(token: unknown): string[];
+}
+//# sourceMappingURL=serialize.d.ts.map

package/lib/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,EACpC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED,6DAA6D;AAC7D,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA+B;IAEvD,qEAAqE;IACrE,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAIzD,yEAAyE;IACzE,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE;CAK/B"}

package/lib/serialize.js

@@ -0,0 +1,38 @@
+/**
+ * Plugin-side concurrency primitives (plan §4.6/§4.7): per-child gate
+ * serialization and execution-token-keyed notice delivery.
+ *
+ * - {@link serializePerKey} runs tasks with the same key strictly in start
+ *   order (a per-key promise chain): concurrent gate evaluations +
+ *   persistence + followup admission for one cold child cannot interleave.
+ *   A failing task propagates its rejection to its own caller only — the
+ *   chain continues for later tasks.
+ * - {@link ExecutionNoticeBus} keys pending gate notices by the tool
+ *   execution identity (`exec.token`, present on both the pre- and
+ *   post-execute payloads), so a failing send can never leak its notice into
+ *   a later call: only the very same execution may take them.
+ *
+ * @module @dsh-cc/subagent-resume-pins/serialize
+ */
+/** Run `task` after any pending same-key task settles; keyed FIFO order. */
+export function serializePerKey(locks, key, task) {
+    const tail = (locks.get(key) ?? Promise.resolve()).then(task, task);
+    locks.set(key, tail.catch(() => { }));
+    return tail;
+}
+/** Pending gate notices keyed by tool execution identity. */
+export class ExecutionNoticeBus {
+    pending = new Map();
+    /** Publish the notices a passing gate produced for ONE execution. */
+    publish(token, notices) {
+        if (notices.length > 0)
+            this.pending.set(token, [...notices]);
+    }
+    /** Take (and clear) the notices published for exactly this execution. */
+    take(token) {
+        const notices = this.pending.get(token);
+        this.pending.delete(token);
+        return notices ?? [];
+    }
+}
+//# sourceMappingURL=serialize.js.map

package/lib/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAC7B,KAAoC,EACpC,GAAW,EACX,IAAsB;IAEtB,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;IACnE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAA;IACpC,OAAO,IAAI,CAAA;AACb,CAAC;AAED,6DAA6D;AAC7D,MAAM,OAAO,kBAAkB;IACZ,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAA;IAEvD,qEAAqE;IACrE,OAAO,CAAC,KAAc,EAAE,OAA0B;QAChD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAA;IAC/D,CAAC;IAED,yEAAyE;IACzE,IAAI,CAAC,KAAc;QACjB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QACvC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC1B,OAAO,OAAO,IAAI,EAAE,CAAA;IACtB,CAAC;CACF"}

package/lib/store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-child pin store: one JSON file per child under `<pinsRoot>/<childId>.json`.
+ *
+ * Durability and coherence contract (plan §4.1/§4.6):
+ * - `write` creates a pin and fails if one already exists (preallocated ids).
+ * - `update` rewrites the file atomically (temp file + rename) AND publishes
+ *   the mutated pin to the store's single synchronous in-memory cache, so no
+ *   stale-cache read can serve the first request after a gate mutation.
+ * - `read` resolves `undefined` for an absent pin (legacy/foreign child,
+ *   pass-through) and a `{kind:'corrupt'}` sentinel for a file that exists
+ *   but is unparseable or unsupported-version — fail-closed callers
+ *   distinguish those; it never throws.
+ * - `remove` tombstone-deletes the file and the cache entry.
+ * - childIds are UUID-ish; anything containing a path separator or `..` is
+ *   rejected before it can traverse out of `pinsRoot`.
+ *
+ * @module @dsh-cc/subagent-resume-pins/store
+ */
+import { type ResumePin, type ResumePinDraft } from './pin.ts';
+/** Distinguishing result for an existing-but-unreadable pin file. */
+export type CorruptPin = {
+    readonly kind: 'corrupt';
+    readonly reason: string;
+};
+/**
+ * Owns the pin files under one root and the single shared in-memory cache the
+ * gate and overlay listeners consult.
+ */
+export declare class PinStore {
+    private readonly pinsRoot;
+    private readonly cache;
+    constructor(pinsRoot: string);
+    /** The on-disk path for one child's pin (validates the childId first). */
+    pathFor(childId: string): string;
+    /**
+     * Read a pin by child id: `undefined` when absent, the corrupt sentinel when
+     * the file exists but cannot be parsed. Read-through: the disk is re-read on
+     * every call (files are tiny, one per model request), so a file deleted or
+     * corrupted out-of-band is never served stale from the cache; the cache only
+     * accelerates nothing — it exists to publish synchronous in-process updates
+     * and is invalidated by any failed disk read.
+     */
+    read(childId: string): ResumePin | CorruptPin | undefined;
+    /** Read only the in-memory cache: `undefined` on miss (no disk access). */
+    getCached(childId: string): ResumePin | undefined;
+    /** Create the pin file; fails when a pin for this child already exists. */
+    write(pin: ResumePin): void;
+    /**
+     * Atomically rewrite a pin through `mutator` (a structural clone is handed
+     * to the mutator) and publish the result to the shared cache synchronously.
+     */
+    update(childId: string, mutator: (draft: ResumePinDraft) => void): ResumePin;
+    /** Tombstone-delete the pin file and its cache entry (idempotent). */
+    remove(childId: string): void;
+    /**
+     * The child ids with a pin file on disk (best-effort; used by the
+     * `list_agents` annotation). Not guaranteed cached or readable.
+     */
+    ids(): string[];
+    private atomicWrite;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAqC,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAEjG,qEAAqE;AACrE,MAAM,MAAM,UAAU,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAS9E;;;GAGG;AACH,qBAAa,QAAQ;IAGP,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;gBAExB,QAAQ,EAAE,MAAM;IAI7C,0EAA0E;IAC1E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAKhC;;;;;;;OAOG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS;IAwBzD,2EAA2E;IAC3E,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIjD,2EAA2E;IAC3E,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI;IAS3B;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,SAAS;IAc5E,sEAAsE;IACtE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7B;;;OAGG;IACH,GAAG,IAAI,MAAM,EAAE;IAUf,OAAO,CAAC,WAAW;CAKpB"}