@deksden-com/dd-flow-cli 0.9.0-beta.80 → 0.9.0-beta.81

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.81
+
+### Patch Changes
+
+- a48e3de: Canonicalize short and full RUN/Work references across native hook receipts, lifecycle admission, Work settlement, and HITL pause/resume. Keep model-facing commands short while preserving scoped ownership checks and report precise receipt mismatch reasons.
+
 ## 0.9.0-beta.75
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.80",
-  "cli_commit": "258058b332954cc3760d11838a3a8a55de4bb0dd",
-  "built_at": "2026-09-19T22:32:15.901Z",
+  "cli_version": "0.9.0-beta.81",
+  "cli_commit": "0e1bd85b82868a501bc9e368e103fe288445370a",
+  "built_at": "2026-09-20T10:24:22.045Z",
   "built_with_canon": {
     "version": "4.1.1",
     "commit": "97f811d33c212ae3497020178b1ed825c7c3ebac",

package/dist/cli/run-cli.js

@@ -9,6 +9,7 @@ import { createContext, createRouterContext } from "../runtime/context.js";
 import { migrateStoreWriter } from "../storage/writer-migration.js";
 import { helpForArgs } from "./help.js";
 import { AppError, isAppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
 import { writeJson } from "../shared/json.js";
 import { archiveProject, prepareProjectArchive, getProjectStatus, migrateProjectIds, registerProject, resolveProject } from "../services/projects.js";
 import { cancelProtocol, getProtocolBlockers, getProtocolStatus, getReadyProtocols, implementProtocol, readyForMerge, registerProtocol, prepareProtocolRegistration, requireProtocol, syncProtocolFromRun, prepareProtocolTransition, transitionProtocol } from "../services/protocols.js";
@@ -1561,7 +1562,7 @@ async function dispatch(args, context, io, scopeProjectRoot = null, classificati
             registerProject(context, { root: projectRoot });
             return findRecentMatchingHookEvent(context, {
                 projectId: requireProjectByRoot(context, resolveProjectRoot(projectRoot)).id,
-                matchKey: stageStartMatchKey(runId, stage, projectRoot, contextSha256),
+                matchKey: entityReferenceVariants(runId).map((reference) => stageStartMatchKey(reference, stage, projectRoot, contextSha256)),
                 errorCode: "trusted_session_binding_required",
                 operation: `vNext ${stage.toUpperCase()} start`
             }).eventKey;

package/dist/services/hooks.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { parse, stringify, TomlError } from "smol-toml";
 import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
 import { parseJsonObject } from "../shared/json.js";
 import { canonicalPath, ensureDir, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
@@ -939,16 +940,25 @@ export function recoveryAcceptMatchKey(runId, recoveryId, projectRoot) {
 export function workLifecycleMatchKey(operation, workId, projectRoot) {
     return crypto.createHash("sha256").update(JSON.stringify({ operation, work_id: workId, project_root: resolveProjectRoot(projectRoot) })).digest("hex");
 }
+function workLifecycleMatchKeys(operation, workId, projectRoot) {
+    return entityReferenceVariants(workId).map((reference) => workLifecycleMatchKey(operation, reference, projectRoot));
+}
+function stageLifecycleMatchKeys(operation, runId, stage, projectRoot, workId) {
+    const runReferences = entityReferenceVariants(runId);
+    const workReferences = workId ? entityReferenceVariants(workId) : [undefined];
+    return [...new Set(runReferences.flatMap((runReference) => workReferences.map((workReference) => stageLifecycleMatchKey(operation, runReference, stage, projectRoot, workReference))))];
+}
 /** Claims a Work terminal command only after its exact hook receipt has proved
  * the physical Session that issued it. Work code performs the owner check. */
 export function claimWorkLifecycleHookEvent(context, input) {
-    const matchKey = workLifecycleMatchKey(input.operation, input.workId, input.projectRoot);
+    const matchKeys = workLifecycleMatchKeys(input.operation, input.workId, input.projectRoot);
     const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
-        projectId: input.projectId, matchKey, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+        projectId: input.projectId, matchKey: matchKeys, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
     }).eventKey;
     const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
-    if (!event?.session_id || event.status !== "observed" || event.match_key !== matchKey) {
-        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { work_id: input.workId, event_key: eventKey });
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !matchKeys.includes(event.match_key)) {
+        const reason = !event ? "event_missing" : !event.session_id ? "identity_missing" : event.status !== "observed" ? "event_consumed" : "target_mismatch";
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { work_id: input.workId, event_key: eventKey, reason, observed_status: event?.status ?? null });
     }
     const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
     if (claimed.changes !== 1)
@@ -958,13 +968,14 @@ export function claimWorkLifecycleHookEvent(context, input) {
 /** Claims a lifecycle command only after its exact hook receipt has proved the
  * physical Session that issued it. Stage code performs the Work-owner check. */
 export function claimStageLifecycleHookEvent(context, input) {
-    const matchKey = stageLifecycleMatchKey(input.operation, input.runId, input.stage, input.projectRoot, input.workId);
+    const matchKeys = stageLifecycleMatchKeys(input.operation, input.runId, input.stage, input.projectRoot, input.workId);
     const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, {
-        projectId: input.projectId, matchKey, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
+        projectId: input.projectId, matchKey: matchKeys, errorCode: "trusted_session_binding_required", operation: input.operation.replace("_", " ")
     }).eventKey;
     const event = context.db.get("SELECT id, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
-    if (!event?.session_id || event.status !== "observed" || event.match_key !== matchKey) {
-        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { run_id: input.runId, stage: input.stage, event_key: eventKey });
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !matchKeys.includes(event.match_key)) {
+        const reason = !event ? "event_missing" : !event.session_id ? "identity_missing" : event.status !== "observed" ? "event_consumed" : "target_mismatch";
+        throw new AppError("trusted_session_binding_required", `${input.operation.replace("_", " ")} requires one fresh matching PreToolUse hook event`, 1, { run_id: input.runId, stage: input.stage, event_key: eventKey, reason, observed_status: event?.status ?? null });
     }
     const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
     if (claimed.changes !== 1)
@@ -1023,11 +1034,15 @@ export function claimRecentMatchingHookEvent(context, input) {
 /** Finds the trusted event that a stage- or Work-specific claimant will atomically claim. */
 export function findRecentMatchingHookEvent(context, input) {
     const freshAfter = new Date(Date.parse(context.now()) - 60_000).toISOString();
+    const matchKeys = Array.isArray(input.matchKey) ? [...new Set(input.matchKey)] : [input.matchKey];
+    const placeholders = matchKeys.map(() => "?").join(", ");
     const find = () => context.db.all(`SELECT id, event_key FROM hook_events
-     WHERE project_id = ? AND match_key = ? AND status = 'observed' AND created_at >= ?
+     WHERE project_id = ? AND match_key IN (${placeholders}) AND status = 'observed' AND created_at >= ?
+       AND NOT (COALESCE(json_extract(outcome_json, '$.effect'), '') = 'no_effect'
+         AND COALESCE(json_extract(outcome_json, '$.disposition'), '') IN ('correctable', 'fatal'))
        AND harness IN ('codex-desktop', 'antigravity-cli')
        AND (? IS NULL OR session_id = ?)
-     ORDER BY id DESC LIMIT 2`, [input.projectId, input.matchKey, freshAfter, input.sessionId ?? null, input.sessionId ?? null]);
+     ORDER BY id DESC LIMIT 2`, [input.projectId, ...matchKeys, freshAfter, input.sessionId ?? null, input.sessionId ?? null]);
     let events = find();
     // Only the qualified non-rewriting transports may correlate the original
     // command: Codex Desktop and Antigravity. New harnesses fail closed by default.
@@ -1037,10 +1052,10 @@ export function findRecentMatchingHookEvent(context, input) {
         events = find();
     }
     if (events.length === 0 || !events[0]?.event_key) {
-        throw new AppError(input.errorCode, `${input.operation} requires a trusted lifecycle receipt. Check native hook delivery; managed commands are admitted from committed native identity, not from model-supplied invocation IDs or updatedInput.`, 1);
+        throw new AppError(input.errorCode, `${input.operation} requires a trusted lifecycle receipt. Check native hook delivery; managed commands are admitted from committed native identity, not from model-supplied invocation IDs or updatedInput.`, 1, { reason: "event_missing" });
     }
     if (events.length > 1) {
-        throw new AppError("ambiguous_lifecycle_receipt", `${input.operation} has more than one fresh matching lifecycle event; provide its exact hook event ID`, 1, { match_key: input.matchKey, event_keys: events.map((event) => event.event_key) });
+        throw new AppError("ambiguous_lifecycle_receipt", `${input.operation} has more than one fresh matching lifecycle event; stop and let the controller reconcile native delivery`, 1, { reason: "multiple_live_events", match_keys: matchKeys, event_keys: events.map((event) => event.event_key) });
     }
     return { id: events[0].id, eventKey: events[0].event_key };
 }
@@ -1065,9 +1080,9 @@ export function bootstrapMatchKey(input) {
     })).digest("hex");
 }
 export function claimWorkStartHookEvent(context, input) {
-    const expected = new Set([workStartMatchKey(input.workId, input.projectRoot, input.recoveryId), workStartMatchKey(shortWorkReference(input.workId), input.projectRoot, input.recoveryId)]);
+    const expected = entityReferenceVariants(input.workId).map((reference) => workStartMatchKey(reference, input.projectRoot, input.recoveryId));
     const event = context.db.get("SELECT id, session_id, agent_id, turn_id, transcript_path, model, agent_type, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
-    if (!event?.session_id || event.status !== "observed" || !event.match_key || !expected.has(event.match_key)) {
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !expected.includes(event.match_key)) {
         throw new AppError("trusted_work_launch_required", "work start requires one fresh matching PreToolUse event", 1, { work_id: input.workId, event_key: input.eventKey });
     }
     const claimed = context.db.run("UPDATE hook_events SET status = 'claimed', claimed_at = ? WHERE id = ? AND status = 'observed'", [context.now(), event.id]);
@@ -1075,13 +1090,12 @@ export function claimWorkStartHookEvent(context, input) {
         throw new AppError("trusted_work_launch_required", "matching work-start hook event was already claimed", 1, { work_id: input.workId });
     return hookSessionIdentity(context, input.projectId, input.eventKey);
 }
-function shortWorkReference(id) { return /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id; }
 /** Claims the exact non-bootstrap stage entry which starts a coordinator Work. */
 export function assertStageStartHookEvent(context, input) {
-    const expected = stageStartMatchKey(input.runId, input.stage, input.projectRoot, input.contextSha256);
+    const expected = entityReferenceVariants(input.runId).map((reference) => stageStartMatchKey(reference, input.stage, input.projectRoot, input.contextSha256));
     const event = context.db.get("SELECT session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
-    if (!event?.session_id || event.status !== "observed" || event.match_key !== expected) {
-        throw new AppError("trusted_stage_launch_required", "stage start requires one fresh matching PreToolUse event", 1, { run_id: input.runId, stage: input.stage, event_key: input.eventKey, expected_match_key: expected, observed_match_key: event?.match_key ?? null, observed_status: event?.status ?? null });
+    if (!event?.session_id || event.status !== "observed" || !event.match_key || !expected.includes(event.match_key)) {
+        throw new AppError("trusted_stage_launch_required", "stage start requires one fresh matching PreToolUse event", 1, { run_id: input.runId, stage: input.stage, event_key: input.eventKey, expected_match_keys: expected, observed_match_key: event?.match_key ?? null, observed_status: event?.status ?? null });
     }
     const identity = hookSessionIdentity(context, input.projectId, input.eventKey);
     assertRecoveryHookCurrent(context, input.projectId, input.runId, identity);
@@ -1115,10 +1129,10 @@ export function stageResumeMatchKey(runId, stage, workId, projectRoot) {
 }
 /** Claims the resume command observed in the Session that received the user answer. */
 export function claimStageResumeHookEvent(context, input) {
-    const matchKey = stageResumeMatchKey(input.runId, input.stage, input.workId, input.projectRoot);
-    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, { projectId: input.projectId, matchKey, sessionId: input.sessionId ?? "", errorCode: "trusted_stage_resume_required", operation: "stage resume" }).eventKey;
+    const matchKeys = entityReferenceVariants(input.runId).flatMap((runReference) => entityReferenceVariants(input.workId).map((workReference) => stageResumeMatchKey(runReference, input.stage, workReference, input.projectRoot)));
+    const eventKey = input.eventKey ?? findRecentMatchingHookEvent(context, { projectId: input.projectId, matchKey: matchKeys, sessionId: input.sessionId ?? "", errorCode: "trusted_stage_resume_required", operation: "stage resume" }).eventKey;
     const event = context.db.get("SELECT id, event_key, session_id, match_key, status FROM hook_events WHERE project_id = ? AND event_key = ?", [input.projectId, eventKey]);
-    if (!event?.event_key || !event.session_id || event.match_key !== matchKey || event.status !== "observed") {
+    if (!event?.event_key || !event.session_id || !event.match_key || !matchKeys.includes(event.match_key) || event.status !== "observed") {
         throw new AppError("trusted_stage_resume_required", "stage resume requires one fresh matching PreToolUse event", 1, { run_id: input.runId, stage: input.stage, work_id: input.workId });
     }
     const identity = hookSessionIdentity(context, input.projectId, event.event_key);

package/dist/services/lifecycle-invocations.js

@@ -4,6 +4,8 @@ import fs from "node:fs";
 import { quote } from "shell-quote";
 import { setTimeout as delay } from "node:timers/promises";
 import { AppError, errorRecord } from "../shared/errors.js";
+import { shortEntityReference } from "../shared/entity-references.js";
+import { resolveWorkReference } from "../storage/work-references.js";
 import { commandOption, parseLifecycleCommand, shellSuffixOffset } from "./lifecycle-command.js";
 import { requireProjectByRoot } from "./projects.js";
 import { assertRunMutationAllowed, assertStageSettlementAllowed, assertWorkSettlementAllowed, recoveryGuard } from "./run-recovery.js";
@@ -73,10 +75,9 @@ function normalizedInvocationValue(key, value) {
         if (runRelative)
             return `@run/${runRelative}`;
     }
-    const entity = /^(PRJ|RUN|WRK)-\d{3,}(?:-|$)/.exec(value)?.[0]?.replace(/-$/, "");
-    if (entity)
-        return entity;
-    return /(?:^|\/)(RCP-\d{3,})$/.exec(value)?.[1] ?? value;
+    if (["positional", "work", "run"].includes(key))
+        return shortEntityReference(value);
+    return key === "retry-check" ? /(?:^|\/)(RCP-\d{3,})$/.exec(value)?.[1] ?? value : value;
 }
 function withoutInvocationId(command, aliases) {
     const parsed = invocation(command);
@@ -88,6 +89,8 @@ function withoutInvocationId(command, aliases) {
         const option = argv[index - 1]?.replace(/^--/, "");
         if (option === "project-root")
             argv[index] = "@project";
+        else if (option === "work" || option === "run")
+            argv[index] = shortEntityReference(argv[index]);
         else if (option && aliases && ["result-file", "decision-file", "verification-file", "context-file"].includes(option) && path.isAbsolute(argv[index])) {
             for (const [name, root] of [["run", aliases.run], ["workspace", aliases.workspace], ["project", aliases.project]]) {
                 if (!root)
@@ -526,10 +529,14 @@ export function assertLifecycleInvocationCurrent(context, scope, command) {
     let workId;
     if (parsed.operation.startsWith("work_")) {
         const target = parsed.args.positional[0] ?? "";
-        const works = context.db.all("SELECT work_id, run_id FROM works WHERE project_id = ? AND (work_id = ? OR (? = 1 AND work_id LIKE ?))", [project.id, target, /^WRK-\d{3,}$/.test(target) ? 1 : 0, `${target}-%`]);
-        if (works.length !== 1 || works[0].run_id !== scope.runId)
-            throw new AppError("invocation_scope_mismatch", "Work does not belong to the issued RUN scope", 1);
-        workId = works[0].work_id;
+        try {
+            workId = resolveWorkReference(context, target, { projectId: project.id, runId: scope.runId }).work_id;
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || !["not_found", "ambiguous_work_alias"].includes(error.code))
+                throw error;
+            throw new AppError("invocation_scope_mismatch", "Work does not belong unambiguously to the issued RUN scope", 1);
+        }
     }
     else if (parsed.operation !== "session_register" && !parsed.args.options.has("bootstrap")) {
         const target = parsed.args.positional[0];

package/dist/services/run-recovery.js

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, setFlowRunRecoveryPaused } from "./runs.js";
@@ -271,7 +272,7 @@ export function resumeRunRecovery(context, input, prepared = prepareRunRecoveryR
 export function acceptRunRecovery(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = requireRecoveryRun(context, project.id, input.runId);
-    const matchKey = recoveryAcceptMatchKey(run.id, input.recoveryId, run.project_root);
+    const matchKey = entityReferenceVariants(run.id).map((reference) => recoveryAcceptMatchKey(reference, input.recoveryId, run.project_root));
     const eventKey = input.hookEventId ?? findRecentMatchingHookEvent(context, { projectId: project.id, matchKey, errorCode: "trusted_recovery_acceptance_required", operation: "run recovery accept" }).eventKey;
     const identity = hookSessionIdentity(context, project.id, eventKey);
     const now = context.now();
@@ -281,7 +282,7 @@ export function acceptRunRecovery(context, input) {
         const guard = recoveryGuard(context, project.id, run.id);
         const binding = context.db.get("SELECT * FROM run_recovery_bindings WHERE recovery_id = ?", [input.recoveryId]);
         const hook = context.db.get("SELECT status, match_key FROM hook_events WHERE id = ?", [identity.hookEventId]);
-        if (!guard || guard.recovery_id !== input.recoveryId || !binding || binding.session_id !== identity.sessionId || binding.harness !== identity.harness || binding.provider_session_id !== identity.providerSessionId || binding.daemon_id !== identity.daemonId || hook?.match_key !== matchKey)
+        if (!guard || guard.recovery_id !== input.recoveryId || !binding || binding.session_id !== identity.sessionId || binding.harness !== identity.harness || binding.provider_session_id !== identity.providerSessionId || binding.daemon_id !== identity.daemonId || !hook?.match_key || !matchKey.includes(hook.match_key))
             throw new AppError("recovery_binding_mismatch", "Recovery acknowledgement does not belong to the authorized physical Session and generation", 1);
         packetReceipt = recoveryPacketReceipt(binding);
         if (binding.harness === "zcode-acp") {

package/dist/services/stage-pause.js

@@ -4,7 +4,9 @@ import os from "node:os";
 import path from "node:path";
 import { lifecycleRetryCommands, managedLifecycleCommand } from "./lifecycle-invocations.js";
 import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
 import { resolveProjectRoot } from "../storage/paths.js";
+import { resolveWorkReference } from "../storage/work-references.js";
 import { findRecentMatchingHookEvent, claimStageResumeHookEvent, stageResumeMatchKey } from "./hooks.js";
 import { requireProjectByRoot } from "./projects.js";
 import { appendFlowRunTimelineEvent, pauseFlowRunStage, resumeFlowRunStage } from "./runs.js";
@@ -96,7 +98,7 @@ export function resumeStageAfterUser(context, input) {
     const { projectRoot, project, run, work, stage, pause, workSession, evidence } = prepareStageResume(context, input);
     const hookEventId = input.hookEventId ?? findRecentMatchingHookEvent(context, {
         projectId: project.id,
-        matchKey: stageResumeMatchKey(run.id, stage.stage, work.work_id, projectRoot),
+        matchKey: entityReferenceVariants(run.id).flatMap((runReference) => entityReferenceVariants(work.work_id).map((workReference) => stageResumeMatchKey(runReference, stage.stage, workReference, projectRoot))),
         errorCode: "trusted_stage_resume_required",
         operation: "stage resume"
     }).eventKey;
@@ -155,7 +157,7 @@ export function resumeStageAfterUser(context, input) {
     return { ok: true, outcome: "resumed", run_id: run.id, work_id: work.work_id, stage: stage.stage, pause_id: pause.id, question_path: pause.question_path, answer_path: answerPath, prompt_path: workSession.prompt_path, worker_prompt_markdown: continuation, next_action: `continue_${stage.stage}` };
 }
 export function stagePauseCommand(context, input) {
-    return managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${input.runId} --stage ${input.stage} --work ${input.workId} --question-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`);
+    return managedLifecycleCommand(context, `${flowCommand(context)} stage pause ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --question-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`);
 }
 /**
  * The only shell form allowed for an agent-owned HITL pause.  Supplying a
@@ -181,7 +183,7 @@ Effect on scope or acceptance:
 USER_QUESTION`;
 }
 function stageResumeCommand(context, input) {
-    return managedLifecycleCommand(context, `${flowCommand(context)} stage resume ${input.runId} --stage ${input.stage} --work ${input.workId} --answer-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`);
+    return managedLifecycleCommand(context, `${flowCommand(context)} stage resume ${shortEntityReference(input.runId)} --stage ${input.stage} --work ${shortEntityReference(input.workId)} --answer-stdin --project-root ${JSON.stringify(input.projectRoot)} --json`);
 }
 export function flowCommand(context) {
     const defaultHome = path.resolve(path.join(os.homedir(), ".dd-flow"));
@@ -207,10 +209,7 @@ function requireRun(context, projectId, id) {
     return rows[0];
 }
 function requireWork(context, projectId, runId, workId) {
-    const work = context.db.get("SELECT work_id, project_id, run_id, status FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [projectId, runId, workId]);
-    if (!work)
-        throw new AppError("not_found", "Work does not belong to this RUN", 1, { run_id: runId, work_id: workId });
-    return work;
+    return resolveWorkReference(context, workId, { projectId, runId });
 }
 function requireStage(run, stage, status) {
     let index;

package/dist/services/work-registry.js

@@ -3,6 +3,8 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants, shortEntityReference } from "../shared/entity-references.js";
+import { resolveWorkReference } from "../storage/work-references.js";
 import { findRecentMatchingHookEvent, claimStageLifecycleHookEvent, claimStageStartHookEvent, claimWorkLifecycleHookEvent, claimWorkStartHookEvent, hookSessionIdentity, workStartMatchKey } from "./hooks.js";
 import { validateSchema } from "./schema-validation.js";
 import { resolveProjectRoot, resolveRunReferences } from "../storage/paths.js";
@@ -41,14 +43,15 @@ export function assertStageLifecycleOwner(context, input) {
     if (!project)
         throw new AppError("not_found", "Project is not registered", 1, { project_root: projectRoot });
     requireRun(context, project.id, input.runId);
+    const scopedWork = input.workId ? requireWork(context, input.workId, { projectId: project.id, runId: input.runId }) : undefined;
     let owner = context.db.get(`SELECT ws.id, ws.work_id, ws.session_id, ws.hook_event_id
        FROM work_sessions ws
        JOIN works w ON w.work_id = ws.work_id
        JOIN sessions s ON s.project_id = w.project_id AND s.session_id = ws.session_id
       WHERE w.project_id = ? AND w.run_id = ? AND ws.status = 'running'
         AND w.status IN ('running', 'paused') AND (w.parent_work_id IS NULL OR s.current_stage = ?)
-        ${input.workId ? "AND w.work_id = ?" : ""}
-      ORDER BY ws.created_at DESC LIMIT 1`, input.workId ? [project.id, input.runId, input.stage, input.workId] : [project.id, input.runId, input.stage]);
+        ${scopedWork ? "AND w.work_id = ?" : ""}
+      ORDER BY ws.created_at DESC LIMIT 1`, scopedWork ? [project.id, input.runId, input.stage, scopedWork.work_id] : [project.id, input.runId, input.stage]);
     if (!owner && input.operation === "stage_finish" && ["code", "code-review"].includes(input.stage)) {
         const row = context.db.get("SELECT run_root, index_json FROM runs WHERE project_id = ? AND id = ?", [project.id, input.runId]);
         const index = row ? JSON.parse(row.index_json) : null;
@@ -371,14 +374,14 @@ export function deleteWork(context, id) {
     prepareWorkDelete(context, id);
     return context.db.writeTransaction(() => { const work = prepareWorkDelete(context, id); context.db.run("DELETE FROM works WHERE work_id = ?", [work.work_id]); refreshRunWorkProjection(context, work.project_id, work.run_id); return { ok: true, deleted: work.work_id }; });
 }
-export function shortWorkId(id) { return /^WRK-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id; }
+export function shortWorkId(id) { return shortEntityReference(id); }
 /**
  * Return the engine-bound command, never a PATH-dependent `dd-flow` token.
  * Fan-out workers run in independently spawned harnesses where the adapter's
  * PATH is not inherited; using the shared lifecycle command keeps them on the
  * same captured runtime as their parent stage.
  */
-export function workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); const recovery = recoveryGuard(context, work.project_id, work.run_id); return managedLifecycleCommand(context, `${flowCommand(context)} work start ${work.work_id} --project-root ${JSON.stringify(run.project_root)}${recovery ? ` --recovery-id ${JSON.stringify(recovery.recovery_id)}` : ""} --json`); }
+export function workStartCommand(context, work) { const run = requireRun(context, work.project_id, work.run_id); const recovery = recoveryGuard(context, work.project_id, work.run_id); return managedLifecycleCommand(context, `${flowCommand(context)} work start ${shortWorkId(work.work_id)} --project-root ${JSON.stringify(run.project_root)}${recovery ? ` --recovery-id ${JSON.stringify(recovery.recovery_id)}` : ""} --json`); }
 export function assertWorkLaunchReady(context, id) {
     ensureWorkRegistry(context);
     const work = requireWork(context, id);
@@ -409,15 +412,7 @@ export function startWork(context, id, input) {
     const recoveryId = recoveryGuard(context, work.project_id, work.run_id)?.recovery_id;
     if (input.recoveryId !== recoveryId)
         throw new AppError("run_recovery_generation_stale", "Work launch must use the exact current recovery packet", 1, { work_id: id, recovery_id: recoveryId ?? null });
-    let hookEventId = input.hookEventId;
-    if (!hookEventId) {
-        try {
-            hookEventId = findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: workStartMatchKey(shortWorkId(work.work_id), run.project_root, recoveryId), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
-        }
-        catch {
-            hookEventId = findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: workStartMatchKey(work.work_id, run.project_root, recoveryId), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
-        }
-    }
+    const hookEventId = input.hookEventId ?? findRecentMatchingHookEvent(context, { projectId: work.project_id, matchKey: entityReferenceVariants(work.work_id).map((reference) => workStartMatchKey(reference, run.project_root, recoveryId)), errorCode: "trusted_session_binding_required", operation: "work start" }).eventKey;
     const eventKey = hookEventId;
     const started = startBoundWork(context, work, run, () => claimWorkStartHookEvent(context, { projectId: work.project_id, eventKey, workId: work.work_id, projectRoot: run.project_root, ...(recoveryId ? { recoveryId } : {}) }), eventKey);
     appendFlowRunTimelineEvent(context, work.project_id, work.run_id, { type: "work_started", work_id: work.work_id, work_session_id: started.work_session_id });
@@ -980,7 +975,7 @@ function renderWorkerPrompt(context, work, run, dependencies) {
     const command = flowCommand(context);
     const packet = codePacket(work);
     const finishWorkCommand = managedLifecycleCommand(context, `${command} work finish ${work.work_id} --result-stdin --project-root ${JSON.stringify(run.project_root)} --json --progress-jsonl`);
-    const failWorkCommand = managedLifecycleCommand(context, `${command} work fail ${work.work_id} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`);
+    const failWorkCommand = managedLifecycleCommand(context, `${command} work fail ${shortWorkId(work.work_id)} --reason "receipt path + exact external or semantic blocker" --project-root ${JSON.stringify(run.project_root)} --json`);
     const mergeWork = parsePayload(work)?.kind === "merge";
     const writeBoundary = mergeWork
         ? ["MERGE does not own product-code repair. Use only the stage packet's merge apply command; resolve only paths that Git reports as unmerged. Do not edit integration code, tests, documentation or configuration to make a gate pass.", "RUN artifacts are read-only evidence: refer to them with run:// URIs and let dd-flow persist your submitted result."]
@@ -1112,22 +1107,13 @@ function codeReviewGroup(work) {
         ? { key: value.key, aspect_ids: value.aspect_ids }
         : null;
 }
-function requireWork(context, id) {
+function requireWork(context, id, explicitScope) {
     ensureWorkRegistry(context);
     const configured = context.env.DD_FLOW_INVOCATION_SCOPE;
     const scope = configured ? JSON.parse(configured) : undefined;
-    const projectId = scope?.projectRoot ? context.db.get("SELECT id FROM projects WHERE root = ?", [scope.projectRoot])?.id : undefined;
-    const scoped = projectId && scope?.runId ? " AND project_id = ? AND run_id = ?" : "";
-    const params = projectId && scope?.runId ? [projectId, scope.runId] : [];
-    const exact = context.db.get(`SELECT ${workColumns} FROM works WHERE work_id = ?${scoped}`, [id, ...params]);
-    if (exact)
-        return exact;
-    if (!/^WRK-\d{3,}$/.test(id))
-        throw new AppError("not_found", "Work is not registered in the current RUN", 1, { work_id: id });
-    const matches = context.db.all(`SELECT ${workColumns} FROM works WHERE work_id LIKE ?${scoped} ORDER BY work_id`, [`${id}-%`, ...params]);
-    if (matches.length !== 1)
-        throw new AppError(matches.length ? "ambiguous_work_alias" : "not_found", matches.length ? "Short Work alias is ambiguous in the current RUN" : "Work is not registered in the current RUN", 1, { work_id: id, matches: matches.map((work) => work.work_id) });
-    return matches[0];
+    const projectId = explicitScope?.projectId ?? (scope?.projectRoot ? context.db.get("SELECT id FROM projects WHERE root = ?", [scope.projectRoot])?.id : undefined);
+    const runId = explicitScope?.runId ?? scope?.runId;
+    return resolveWorkReference(context, id, { projectId, runId });
 }
 function requireRun(context, projectId, runId) { const run = context.db.get("SELECT r.id, r.run_root, r.workspace_root, p.root AS project_root FROM runs r JOIN projects p ON p.id = r.project_id WHERE r.project_id = ? AND r.id = ?", [projectId, runId]); if (!run?.run_root)
     throw new AppError("runtime_missing", "RUN artifact root is unavailable", 1, { run_id: runId }); return run; }

package/dist/shared/entity-references.js

@@ -0,0 +1,8 @@
+/** Stable model-facing reference for persisted project, RUN and Work IDs. */
+export function shortEntityReference(id) {
+    return /^(?:PRJ|RUN|WRK)-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id;
+}
+/** Accepted spellings of one already-resolved entity. Wrong full slugs stay distinct. */
+export function entityReferenceVariants(id) {
+    return [...new Set([id, shortEntityReference(id)])];
+}

package/dist/storage/work-references.js

@@ -0,0 +1,23 @@
+import { AppError } from "../shared/errors.js";
+/** Read-only lookup; scope applies to exact IDs as well as short aliases. */
+export function resolveWorkReference(context, id, scope = {}) {
+    const clauses = ["1 = 1"];
+    const params = [];
+    if (scope.projectId) {
+        clauses.push("project_id = ?");
+        params.push(scope.projectId);
+    }
+    if (scope.runId) {
+        clauses.push("run_id = ?");
+        params.push(scope.runId);
+    }
+    const where = clauses.join(" AND ");
+    const exact = context.db.get(`SELECT * FROM works WHERE ${where} AND work_id = ?`, [...params, id]);
+    if (exact)
+        return exact;
+    const matches = /^WRK-\d{3,}$/.test(id)
+        ? context.db.all(`SELECT * FROM works WHERE ${where} AND work_id LIKE ? ORDER BY work_id`, [...params, `${id}-%`]) : [];
+    if (matches.length !== 1)
+        throw new AppError(matches.length ? "ambiguous_work_alias" : "not_found", matches.length ? "Short Work alias is ambiguous in the current RUN" : "Work is not registered in the current RUN", 1, { work_id: id, matches: matches.map(work => work.work_id) });
+    return matches[0];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.80",
+  "version": "0.9.0-beta.81",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {