@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/dist/core/schema/fields-file.js

@@ -4,9 +4,11 @@
  * Resolves configurable schema, fields, statuses, and workflows for Fields File.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="79b35844-ab8e-5b6f-9975-4dd85b210bcb")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="575b0c3a-9ce1-504f-a24e-d8854e898f17")}catch(e){}}();
 import { RUNTIME_FIELD_COMMAND_VALUES, RUNTIME_FIELD_TYPE_VALUES, } from "../../types/index.js";
 import { ITEM_METADATA_KEY_ORDER } from "../shared/constants.js";
+import { normalizeStatusToken as normalizeFieldKey } from "./status-token.js";
+export { normalizeStatusToken as normalizeFieldKey } from "./status-token.js";
 /**
  * Pure logic for the `pm schema add-field` / `pm schema remove-field` commands
  * and the `list-fields` / `show-field` inspectors. The CLI command file
@@ -52,15 +54,6 @@ export const BUILTIN_FIELD_KEYS = new Set([
 ]);
 /** The default commands a field is wired onto when `--commands` is omitted, matching the runtime default in runtime-schema.ts (normalizeRuntimeFieldDefinition). */
 const DEFAULT_FIELD_COMMANDS = ["create", "update"];
-/** Normalizes a field key using the same rule as runtime-schema.ts: lowercase and collapse any run of whitespace/hyphens into a single underscore. */
-export function normalizeFieldKey(value) {
-    return typeof value === "string"
-        ? value
-            .trim()
-            .toLowerCase()
-            .replaceAll(/[\s-]+/g, "_")
-        : "";
-}
 /** Normalizes a CLI flag token: strip a leading `--`, lowercase, and collapse whitespace/underscore runs to a single hyphen (matches normalizeCliToken in runtime-schema.ts). */
 function normalizeCliToken(value) {
     if (typeof value !== "string") {
@@ -293,4 +286,4 @@ function applyBooleanFlag(definition, key, value) {
     }
 }
 //# sourceMappingURL=fields-file.js.map
-//# debugId=79b35844-ab8e-5b6f-9975-4dd85b210bcb
+//# debugId=575b0c3a-9ce1-504f-a24e-d8854e898f17

package/dist/core/schema/runtime-schema.js

@@ -4,11 +4,12 @@
  * Resolves configurable schema, fields, statuses, and workflows for Runtime Schema.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="febba42b-dfd0-549a-a6d9-c30edb321d9d")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a9ff482a-f9f9-5e35-88d0-240db815ec08")}catch(e){}}();
 import path from "node:path";
 import { pathExists, readFileIfExists, writeFileAtomic, } from "../fs/fs-utils.js";
 import { DEFAULT_STATUS_DEFINITIONS, DEFAULT_WORKFLOW_DEFINITION, } from "../shared/constants.js";
 import { RUNTIME_FIELD_COMMAND_VALUES, RUNTIME_FIELD_TYPE_VALUES, RUNTIME_STATUS_ROLE_VALUES, RUNTIME_UNKNOWN_FIELD_POLICY_VALUES, STATUS_VALUES, } from "../../types/index.js";
+import { normalizeStatusToken } from "./status-token.js";
 /** Fallback runtime schema file paths used when callers do not provide an override. */
 export const DEFAULT_RUNTIME_SCHEMA_FILE_PATHS = Object.freeze({
     types: "schema/types.json",
@@ -39,14 +40,6 @@ function normalizeStringList(values) {
             .filter((value) => value.length > 0)),
     ].sort((left, right) => left.localeCompare(right));
 }
-function normalizeStatusToken(value) {
-    return typeof value === "string"
-        ? value
-            .trim()
-            .toLowerCase()
-            .replaceAll(/[\s-]+/g, "_")
-        : "";
-}
 function normalizeStatusId(value) {
     if (typeof value !== "string" || value.length === 0) {
         return undefined;
@@ -698,4 +691,4 @@ export function statusIsTerminal(status, registry) {
     return registry.terminal_statuses.has(normalized);
 }
 //# sourceMappingURL=runtime-schema.js.map
-//# debugId=febba42b-dfd0-549a-a6d9-c30edb321d9d
+//# debugId=a9ff482a-f9f9-5e35-88d0-240db815ec08

package/dist/core/schema/status-defs-file.d.ts

@@ -1,4 +1,5 @@
 import type { RuntimeStatusDefinition, RuntimeStatusRole } from "../../types/index.js";
+export { normalizeStatusToken } from "./status-token.js";
 export type { RuntimeStatusDefinition, RuntimeStatusRole, } from "../../types/index.js";
 /** The 5 lifecycle status ids that ship as built-in defaults and may never be removed (their normalized ids match DEFAULT_RUNTIME_STATUS_DEFINITIONS: open/in_progress/blocked/closed/canceled). `draft` is also a default but the acceptance criteria enumerate the 5 terminal/active ids explicitly, so the guard derives the full set from the canonical defaults to stay in sync. */
 export declare const BUILTIN_STATUS_IDS: ReadonlySet<string>;
@@ -51,8 +52,6 @@ export interface RemoveStatusDefResult {
     /** The removed definition, when one matched the requested id. */
     definition?: RuntimeStatusDefinition;
 }
-/** Normalizes a status token using the same rules as runtime-schema.ts: lowercase and collapse any run of whitespace/hyphens into a single underscore. */
-export declare function normalizeStatusToken(value: unknown): string;
 /**
  * Validates and normalizes raw add-status CLI input. Throws a plain Error with a
  * stable message when the id is missing/empty or a role is not one of

package/dist/core/schema/status-defs-file.js

@@ -4,10 +4,11 @@
  * Resolves configurable schema, fields, statuses, and workflows for Status Defs File.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f81297bd-06ac-5aa4-9e1b-802fb50c9cd0")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="3eac0218-43c9-5bd2-8eaf-589d02d2c8ad")}catch(e){}}();
 import { RUNTIME_STATUS_ROLE_VALUES } from "../../types/index.js";
 import { DEFAULT_RUNTIME_STATUS_DEFINITIONS } from "./runtime-schema.js";
-import { evictOldestMemoEntries } from "../shared/memo.js";
+import { normalizeStatusToken } from "./status-token.js";
+export { normalizeStatusToken } from "./status-token.js";
 /**
  * Pure logic for the `pm schema add-status` / `pm schema remove-status`
  * commands. The CLI command file (schema.ts) owns IO/governance; everything
@@ -20,37 +21,8 @@ import { evictOldestMemoEntries } from "../shared/memo.js";
  * into the persisted file.
  */
 const RUNTIME_STATUS_ROLE_SET = new Set(RUNTIME_STATUS_ROLE_VALUES);
-/**
- * Memo for {@link normalizeStatusToken}. Status ranking inside sort comparators
- * normalizes the same handful of status strings O(n log n) times per corpus scan, and
- * the trim/lowercase/regex pipeline shows up in list/next/context profiles. The cap
- * bounds memory in long-lived hosts against unbounded arbitrary inputs; half-eviction keeps the
- * newest-inserted half when the cap is hit. Declared before
- * BUILTIN_STATUS_IDS, whose module-level initializer already normalizes tokens.
- */
-const STATUS_TOKEN_MEMO_MAX_ENTRIES = 2_000;
-const statusTokenMemo = new Map();
 /** The 5 lifecycle status ids that ship as built-in defaults and may never be removed (their normalized ids match DEFAULT_RUNTIME_STATUS_DEFINITIONS: open/in_progress/blocked/closed/canceled). `draft` is also a default but the acceptance criteria enumerate the 5 terminal/active ids explicitly, so the guard derives the full set from the canonical defaults to stay in sync. */
 export const BUILTIN_STATUS_IDS = new Set(DEFAULT_RUNTIME_STATUS_DEFINITIONS.map((definition) => normalizeStatusToken(definition.id)).filter((id) => id.length > 0));
-/** Normalizes a status token using the same rules as runtime-schema.ts: lowercase and collapse any run of whitespace/hyphens into a single underscore. */
-export function normalizeStatusToken(value) {
-    if (typeof value !== "string") {
-        return "";
-    }
-    const memoized = statusTokenMemo.get(value);
-    if (memoized !== undefined) {
-        return memoized;
-    }
-    const normalized = value
-        .trim()
-        .toLowerCase()
-        .replaceAll(/[\s-]+/g, "_");
-    if (statusTokenMemo.size >= STATUS_TOKEN_MEMO_MAX_ENTRIES) {
-        evictOldestMemoEntries(statusTokenMemo);
-    }
-    statusTokenMemo.set(value, normalized);
-    return normalized;
-}
 function dedupeTokens(values) {
     const seen = new Set();
     for (const value of values) {
@@ -250,4 +222,4 @@ export function assertStatusTokensAvailable(input, resolvedAliasToId) {
     }
 }
 //# sourceMappingURL=status-defs-file.js.map
-//# debugId=f81297bd-06ac-5aa4-9e1b-802fb50c9cd0
+//# debugId=3eac0218-43c9-5bd2-8eaf-589d02d2c8ad

package/dist/core/schema/status-token.d.ts

@@ -0,0 +1,2 @@
+/** Lowercase a status token and collapse whitespace or hyphen runs to one underscore. */
+export declare function normalizeStatusToken(value: unknown): string;

package/dist/core/schema/status-token.js

@@ -0,0 +1,32 @@
+/**
+ * @module core/schema/status-token
+ *
+ * Owns the canonical bounded status-token normalization primitive used by
+ * schema files, runtime registries, workflows, and package-facing SDK helpers.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d6056922-237d-525a-b354-687493a4e123")}catch(e){}}();
+import { evictOldestMemoEntries } from "../shared/memo.js";
+const STATUS_TOKEN_MEMO_MAX_ENTRIES = 2_000;
+const statusTokenMemo = new Map();
+/** Lowercase a status token and collapse whitespace or hyphen runs to one underscore. */
+export function normalizeStatusToken(value) {
+    if (typeof value !== "string") {
+        return "";
+    }
+    const memoized = statusTokenMemo.get(value);
+    if (memoized !== undefined) {
+        return memoized;
+    }
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replaceAll(/[\s-]+/g, "_");
+    if (statusTokenMemo.size >= STATUS_TOKEN_MEMO_MAX_ENTRIES) {
+        evictOldestMemoEntries(statusTokenMemo);
+    }
+    statusTokenMemo.set(value, normalized);
+    return normalized;
+}
+//# sourceMappingURL=status-token.js.map
+//# debugId=d6056922-237d-525a-b354-687493a4e123

package/dist/core/schema/type-workflows.d.ts

@@ -4,6 +4,7 @@
  * Resolves configurable schema, fields, statuses, and workflows for Type Workflows.
  */
 import type { RuntimeSchemaSettings } from "../../types/index.js";
+export { normalizeStatusToken } from "./status-token.js";
 /**
  * Per-type allowed-transition support (governance.workflow_enforcement).
  *
@@ -51,8 +52,6 @@ export interface EvaluateTransitionResult {
     /** Allowed [from, to] pairs for the matched type (normalized ids). Empty when the type is unrestricted. */
     allowedTransitions: [string, string][];
 }
-/** Normalize a status token the same way runtime-schema statuses are normalized. */
-export declare function normalizeStatusToken(value: unknown): string;
 /**
  * Normalize the raw type_workflows from a runtime schema into a deduped,
  * lower-cased-type list with normalized status tokens.

package/dist/core/schema/type-workflows.js

@@ -1,14 +1,7 @@
-/** Normalize a status token the same way runtime-schema statuses are normalized. */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8370105a-2103-5425-8dd8-b621107f3bd8")}catch(e){}}();
-export function normalizeStatusToken(value) {
-    return typeof value === "string"
-        ? value
-            .trim()
-            .toLowerCase()
-            .replaceAll(/[\s-]+/g, "_")
-        : "";
-}
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c4e316a0-823d-5722-9e15-6d741ae44f1b")}catch(e){}}();
+import { normalizeStatusToken } from "./status-token.js";
+export { normalizeStatusToken } from "./status-token.js";
 function normalizeTypeName(value) {
     return typeof value === "string" ? value.trim().toLowerCase() : "";
 }
@@ -109,4 +102,4 @@ export function describeAllowedTransitions(allowedTransitions) {
         .join(", ");
 }
 //# sourceMappingURL=type-workflows.js.map
-//# debugId=8370105a-2103-5425-8dd8-b621107f3bd8
+//# debugId=c4e316a0-823d-5722-9e15-6d741ae44f1b

package/dist/core/session/session-state.d.ts

@@ -9,11 +9,58 @@
 export interface SessionState {
     /** Value that configures or reports focused item for this contract. */
     focused_item?: string;
+    /** Privacy-safe semantic work context partitioned by agent invocation. */
+    semantic_attribution?: Record<string, AgentSemanticAttribution>;
+}
+/** Bounded inferred work context consumed by mutation provenance. */
+export interface AgentSemanticAttribution {
+    /** Controlled role inferred from the current work lifecycle. */
+    role: "implementer" | "planner" | "release-operator";
+    /** Stable item or workset identity, never prompt text. */
+    topic: string;
+    /** Confidence attached to the inferred observation. */
+    confidence: "high" | "medium";
+    /** Versioned inference rule understood by history consumers. */
+    rule_version: "v2";
+    /** Bounded item and lineage references supporting the inference. */
+    evidence: string[];
+    /** Claimed items currently contributing to the workset. */
+    active_item_ids: string[];
+    /** Explicitly focused item when focus takes precedence over claims. */
+    focused_item_id?: string;
 }
 /** Implements get session state path for the public runtime surface of this module. */
 export declare function getSessionStatePath(pmRoot: string): string;
 /** Implements read session state for the public runtime surface of this module. */
 export declare function readSessionState(pmRoot: string): Promise<SessionState>;
+/** Derive a non-secret state key from a claim principal. */
+export declare function semanticAttributionKey(principal: string): string;
+/** Record a successful claim as incremental semantic session evidence. */
+export declare function recordClaimedWorkAttribution(params: {
+    pmRoot: string;
+    principal: string;
+    itemId: string;
+    lineageIds?: readonly string[];
+}): Promise<void>;
+/** Remove a released item from incremental semantic session evidence. */
+export declare function releaseClaimedWorkAttribution(params: {
+    pmRoot: string;
+    principal: string;
+    itemId: string;
+}): Promise<void>;
+/** Set or clear focus as the highest-confidence semantic topic. */
+export declare function recordFocusedWorkAttribution(params: {
+    pmRoot: string;
+    principal: string;
+    itemId?: string;
+    lineageIds?: readonly string[];
+}): Promise<void>;
+/** Read one privacy-bounded inferred attribution without making mutations fail. */
+export declare function readAgentSemanticAttributionSync(params: {
+    cwd: string;
+    env: Readonly<Record<string, string | undefined>>;
+    key: string | undefined;
+}): AgentSemanticAttribution | undefined;
 /** Implements get focused item for the public runtime surface of this module. */
 export declare function getFocusedItem(pmRoot: string): Promise<string | undefined>;
 /** Implements set focused item for the public runtime surface of this module. */

package/dist/core/session/session-state.js

@@ -4,12 +4,57 @@
  * Maintains lightweight agent session state for contextual workflows.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="611f01b6-0c72-5ea2-a44f-78877c69706c")}catch(e){}}();
-import { promises as fs } from "node:fs";
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="424b9eb3-6b34-5ab0-a3f5-db61fbca12cf")}catch(e){}}();
+import { createHash } from "node:crypto";
+import { existsSync, promises as fs, readFileSync } from "node:fs";
 import path from "node:path";
 import { writeFileAtomic } from "../fs/fs-utils.js";
 import { getRuntimePath } from "../store/paths.js";
 const SESSION_FILENAME = "session.json";
+function isBoundedNonEmptyString(value, maximum) {
+    return (typeof value === "string" && value.length > 0 && value.length <= maximum);
+}
+function parseSemanticAttribution(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    const validRole = ["implementer", "planner", "release-operator"].includes(String(record.role));
+    const validConfidence = ["high", "medium"].includes(String(record.confidence));
+    const validTopic = isBoundedNonEmptyString(record.topic, 256);
+    const validEvidence = Array.isArray(record.evidence) &&
+        record.evidence.length <= 32 &&
+        record.evidence.every((entry) => typeof entry === "string" && entry.length <= 128);
+    const validActiveItems = Array.isArray(record.active_item_ids) &&
+        record.active_item_ids.length <= 64 &&
+        record.active_item_ids.every((entry) => isBoundedNonEmptyString(entry, 128));
+    const validFocus = record.focused_item_id === undefined ||
+        isBoundedNonEmptyString(record.focused_item_id, 128);
+    if (![
+        validRole,
+        validConfidence,
+        validTopic,
+        validEvidence,
+        validActiveItems,
+        validFocus,
+        record.rule_version === "v2",
+    ].every(Boolean)) {
+        return undefined;
+    }
+    return record;
+}
+function parseSemanticAttributionMap(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value)
+        .slice(0, 128)
+        .flatMap(([key, attribution]) => {
+        const parsed = parseSemanticAttribution(attribution);
+        return parsed && key.length <= 128 ? [[key, parsed]] : [];
+    });
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
 /** Implements get session state path for the public runtime surface of this module. */
 export function getSessionStatePath(pmRoot) {
     return path.join(getRuntimePath(pmRoot), SESSION_FILENAME);
@@ -24,11 +69,20 @@ export async function readSessionState(pmRoot) {
             Array.isArray(parsed)) {
             return {};
         }
-        const focused = parsed.focused_item;
+        const record = parsed;
+        const focused = record.focused_item;
+        const semanticAttribution = parseSemanticAttributionMap(record.semantic_attribution);
         if (typeof focused === "string" && focused.trim().length > 0) {
-            return { focused_item: focused };
+            return {
+                focused_item: focused,
+                ...(semanticAttribution
+                    ? { semantic_attribution: semanticAttribution }
+                    : {}),
+            };
         }
-        return {};
+        return semanticAttribution
+            ? { semantic_attribution: semanticAttribution }
+            : {};
     }
     catch {
         return {};
@@ -39,6 +93,153 @@ async function writeSessionState(pmRoot, state) {
     await fs.mkdir(path.dirname(target), { recursive: true });
     await writeFileAtomic(target, JSON.stringify(state));
 }
+/** Derive a non-secret state key from a claim principal. */
+export function semanticAttributionKey(principal) {
+    const instance = /#([a-f0-9]{24})$/u.exec(principal.trim())?.[1];
+    return (instance ??
+        `author-${createHash("sha256").update(principal).digest("hex").slice(0, 24)}`);
+}
+function normalizedEvidence(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))]
+        .slice(0, 32)
+        .map((value) => value.slice(0, 128));
+}
+function worksetTopic(activeItemIds) {
+    const ids = [...new Set(activeItemIds)].sort((left, right) => left.localeCompare(right));
+    if (ids.length === 1)
+        return ids[0];
+    const complete = `workset:${ids.join("+")}`;
+    if (complete.length <= 256)
+        return complete;
+    const visible = ids.join("+").slice(0, 230);
+    return `workset:${visible}+${createHash("sha256").update(ids.join("\0")).digest("hex").slice(0, 12)}`;
+}
+async function updateSemanticAttribution(pmRoot, key, mutate) {
+    const state = await readSessionState(pmRoot);
+    const attributions = { ...state.semantic_attribution };
+    const next = mutate(attributions[key]);
+    if (next === undefined)
+        delete attributions[key];
+    else
+        attributions[key] = next;
+    const nextState = { ...state };
+    if (Object.keys(attributions).length === 0) {
+        delete nextState.semantic_attribution;
+    }
+    else {
+        nextState.semantic_attribution = attributions;
+    }
+    await writeSessionState(pmRoot, nextState);
+}
+/** Record a successful claim as incremental semantic session evidence. */
+export async function recordClaimedWorkAttribution(params) {
+    const key = semanticAttributionKey(params.principal);
+    await updateSemanticAttribution(params.pmRoot, key, (current) => {
+        const activeItemIds = [
+            ...new Set([...(current?.active_item_ids ?? []), params.itemId]),
+        ]
+            .slice(-64)
+            .sort((left, right) => left.localeCompare(right));
+        const focusedItemId = current?.focused_item_id;
+        return {
+            role: "implementer",
+            topic: focusedItemId ?? worksetTopic(activeItemIds),
+            confidence: focusedItemId ? "high" : "medium",
+            rule_version: "v2",
+            evidence: normalizedEvidence([
+                ...activeItemIds.map((id) => `claim:${id}`),
+                ...(focusedItemId ? [`focus:${focusedItemId}`] : []),
+                ...(params.lineageIds ?? []).map((id) => `lineage:${id}`),
+            ]),
+            active_item_ids: activeItemIds,
+            ...(focusedItemId ? { focused_item_id: focusedItemId } : {}),
+        };
+    });
+}
+/** Remove a released item from incremental semantic session evidence. */
+export async function releaseClaimedWorkAttribution(params) {
+    const key = semanticAttributionKey(params.principal);
+    await updateSemanticAttribution(params.pmRoot, key, (current) => {
+        if (!current)
+            return undefined;
+        const activeItemIds = current.active_item_ids.filter((id) => id !== params.itemId);
+        if (activeItemIds.length === 0 && !current.focused_item_id)
+            return undefined;
+        const focusedItemId = current.focused_item_id;
+        return {
+            ...current,
+            role: "release-operator",
+            topic: focusedItemId ?? worksetTopic(activeItemIds),
+            confidence: focusedItemId ? "high" : "medium",
+            evidence: normalizedEvidence([
+                ...activeItemIds.map((id) => `claim:${id}`),
+                ...(focusedItemId ? [`focus:${focusedItemId}`] : []),
+                `release:${params.itemId}`,
+            ]),
+            active_item_ids: activeItemIds,
+        };
+    });
+}
+/** Set or clear focus as the highest-confidence semantic topic. */
+export async function recordFocusedWorkAttribution(params) {
+    const key = semanticAttributionKey(params.principal);
+    await updateSemanticAttribution(params.pmRoot, key, (current) => {
+        const activeItemIds = current?.active_item_ids ?? [];
+        if (!params.itemId && activeItemIds.length === 0)
+            return undefined;
+        const focusedItemId = params.itemId;
+        return {
+            role: focusedItemId ? "planner" : current.role,
+            topic: focusedItemId ?? worksetTopic(activeItemIds),
+            confidence: focusedItemId ? "high" : "medium",
+            rule_version: "v2",
+            evidence: normalizedEvidence([
+                ...activeItemIds.map((id) => `claim:${id}`),
+                ...(focusedItemId ? [`focus:${focusedItemId}`] : []),
+                ...(params.lineageIds ?? []).map((id) => `lineage:${id}`),
+            ]),
+            active_item_ids: activeItemIds,
+            ...(focusedItemId ? { focused_item_id: focusedItemId } : {}),
+        };
+    });
+}
+function resolveAttributionRoot(cwd, env) {
+    const configured = env.PM_PATH?.trim();
+    if (configured) {
+        const resolved = path.resolve(cwd, configured);
+        if (existsSync(path.join(resolved, "settings.json")))
+            return resolved;
+        const nested = path.join(resolved, ".agents", "pm");
+        if (existsSync(path.join(nested, "settings.json")))
+            return nested;
+    }
+    let cursor = path.resolve(cwd);
+    for (let depth = 0; depth < 32; depth += 1) {
+        const candidate = path.join(cursor, ".agents", "pm");
+        if (existsSync(path.join(candidate, "settings.json")))
+            return candidate;
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    return undefined;
+}
+/** Read one privacy-bounded inferred attribution without making mutations fail. */
+export function readAgentSemanticAttributionSync(params) {
+    if (!params.key)
+        return undefined;
+    const pmRoot = resolveAttributionRoot(params.cwd, params.env);
+    if (!pmRoot)
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(getSessionStatePath(pmRoot), "utf8"));
+        return parseSemanticAttribution(parsed.semantic_attribution?.[params.key]);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Implements get focused item for the public runtime surface of this module. */
 export async function getFocusedItem(pmRoot) {
     const state = await readSessionState(pmRoot);
@@ -57,4 +258,4 @@ export async function clearFocusedItem(pmRoot) {
     await writeSessionState(pmRoot, next);
 }
 //# sourceMappingURL=session-state.js.map
-//# debugId=611f01b6-0c72-5ea2-a44f-78877c69706c
+//# debugId=424b9eb3-6b34-5ab0-a3f5-db61fbca12cf

package/dist/core/shared/author.d.ts

@@ -2,7 +2,7 @@ import { type AgentEpisodeIdentity, type AgentSessionContext } from "./agent-ses
 /** Stable provenance categories recorded beside newly appended history authors. */
 export type AuthorSource = "asserted" | "configured" | "detected" | "unknown";
 /** Stable source categories for model observations recorded in mutation history. */
-export type AgentModelSource = "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe";
+export type AgentModelSource = "override" | "environment" | "mcp_client" | "argv" | "host" | "session" | "probe" | "inferred";
 /** Stable built-in provenance dimensions understood by the default runtime. */
 export declare const AGENT_PROVENANCE_DIMENSIONS: readonly ["model", "effort", "role", "topic", "version"];
 /** Built-in, bounded local resolver names accepted by harness descriptors. */
@@ -13,6 +13,12 @@ export interface AgentProvenanceObservation {
     value: string;
     /** Signal class that supplied the value. */
     source: AgentModelSource;
+    /** Confidence attached to a semantic inference. */
+    confidence?: "high" | "medium" | "low";
+    /** Versioned inference rule when the value was derived. */
+    rule_version?: "v2";
+    /** Bounded item and lineage references supporting an inference. */
+    evidence?: readonly string[];
 }
 /**
  * Extensible provenance dimensions. A null value explicitly means that the
@@ -24,7 +30,7 @@ export type AgentProvenanceAbsenceReason = "harness_unavailable" | "resolver_fai
 /** Machine-readable resolution outcome for one provenance dimension. */
 export interface AgentProvenanceOutcome {
     /** Whether the dimension resolved without retaining private source material. */
-    status: "resolved" | "unavailable" | "failed";
+    status: "resolved" | "unavailable" | "not_configured" | "failed";
     /** Stable bounded reason for absent or rejected values. */
     reason?: AgentProvenanceAbsenceReason;
     /** Resolver name when a bounded local resolver was attempted. */