@danypops/papyrus 0.44.5 → 0.44.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.44.5",
+  "version": "0.44.6",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/adapters/sqlite-artifact-store.ts

@@ -15,6 +15,7 @@ import type { ArtifactTrashRecord } from "../domain/artifact-trash.ts";
 import {
 	createArtifact,
 	getArtifact,
+	getArtifactByAlias,
 	getArtifactTrash,
 	linkArtifacts,
 	listArtifactTrash,
@@ -47,6 +48,10 @@ export class SQLiteArtifactStore implements AtomicArtifactStore, ArtifactTrashSt
 		return getArtifact(this.db, id, options);
 	}
 
+	getByAlias(alias: string): Artifact | null {
+		return getArtifactByAlias(this.db, alias);
+	}
+
 	query(filter: ArtifactQuery): Artifact[] {
 		return queryArtifacts(this.db, filter);
 	}

package/src/cli.ts

@@ -196,7 +196,7 @@ function usage(): never {
 
 type TaskCliClient = Pick<PapyrusClient, "call">;
 type MigrationResult = { from: number; to: number; applied: string[] };
-type CliArtifact = { id: string; title: string; status: string; body?: string };
+type CliArtifact = { id: string; alias: string; title: string; status: string; body?: string };
 type CliTaskLease = {
 	taskId: string;
 	owner: string;
@@ -239,7 +239,7 @@ function parseJsonAnyFlag(value: string | undefined, flag: string): unknown {
 }
 
 function artifactLabel(artifact: CliArtifact): string {
-	return `${artifact.id} ${artifact.title}`;
+	return `${artifact.alias} ${artifact.title}`;
 }
 
 function planText(plan: TaskExecutionPlan): string {

package/src/constants.ts

@@ -9,7 +9,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 23;
+export const SQLITE_SCHEMA_VERSION = 24;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;

package/src/db.ts

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import { dirname } from "node:path";
 import { runMigrations, type SqliteMigrationRunner } from "@danypops/vehicle-server/storage";
 import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
+import { generateUniqueAlias, slugify } from "./domain/artifact-alias.ts";
 
 const require_ = createRequire(import.meta.url);
 const IS_BUN = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
@@ -99,8 +100,10 @@ CREATE TABLE IF NOT EXISTS artifacts (
 	extra       TEXT DEFAULT '{}',
 	created_at  TEXT NOT NULL,
 	updated_at  TEXT NOT NULL,
+	alias       TEXT,
 	FOREIGN KEY (kind, status) REFERENCES statuses(kind, name)
 );
+CREATE UNIQUE INDEX IF NOT EXISTS artifacts_alias_idx ON artifacts(alias);
 CREATE TABLE IF NOT EXISTS edges (
 	from_id     TEXT NOT NULL REFERENCES artifacts(id),
 	relation    TEXT NOT NULL REFERENCES relation_names(name),
@@ -702,6 +705,33 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 24,
+		name: "artifact-aliases",
+		// See domain/artifact-alias.ts. A real column + unique index, backfilled here rather than
+		// computed lazily on read -- IF NOT EXISTS/guarded column add throughout since a fixture
+		// that bootstraps from the current SCHEMA text (which already declares alias) and then only
+		// fakes an older user_version to exercise this migration path must not fail with "duplicate
+		// column name", the same class of concern version 16's comment covers.
+		up: (db) => {
+			const existing = new Set((db.prepare("PRAGMA table_info(artifacts)").all() as Array<{ name: string }>).map((row) => row.name));
+			if (!existing.has("alias")) db.exec("ALTER TABLE artifacts ADD COLUMN alias TEXT");
+			const rows = db.prepare("SELECT id, title FROM artifacts WHERE alias IS NULL ORDER BY created_at, id").all() as Array<{
+				id: string;
+				title: string;
+			}>;
+			const taken = new Set(
+				(db.prepare("SELECT alias FROM artifacts WHERE alias IS NOT NULL").all() as Array<{ alias: string }>).map((row) => row.alias),
+			);
+			const update = db.prepare("UPDATE artifacts SET alias = ? WHERE id = ?");
+			for (const row of rows) {
+				const alias = generateUniqueAlias(slugify(row.title), (candidate) => taken.has(candidate));
+				taken.add(alias);
+				update.run(alias, row.id);
+			}
+			db.exec("CREATE UNIQUE INDEX IF NOT EXISTS artifacts_alias_idx ON artifacts(alias)");
+		},
+	},
 ];
 
 /**

package/src/domain/artifact-alias.ts

@@ -0,0 +1,36 @@
+/**
+ * A short, globally-unique, human/agent-typeable name for an artifact -- alongside its
+ * opaque UUID identity (ops.ts's createArtifact), not instead of it. Derived from title by
+ * default so the alias stays recognizable, but title itself is free-form prose and not
+ * unique -- this module owns turning that into something safe to type, remember, and index.
+ */
+
+const MAX_ALIAS_LENGTH = 50;
+const FALLBACK_BASE = "artifact";
+const ALIAS_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** Lowercased, hyphen-separated, ASCII-alphanumeric-only; never empty (falls back to a generic base). */
+export function slugify(title: string): string {
+	const slug = title
+		.toLowerCase()
+		.replace(/'/g, "")
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, MAX_ALIAS_LENGTH)
+		.replace(/-+$/g, "");
+	return slug.length > 0 ? slug : FALLBACK_BASE;
+}
+
+/** Appends the lowest available "-N" suffix (starting at 2) until `isTaken` reports free. */
+export function generateUniqueAlias(base: string, isTaken: (candidate: string) => boolean): string {
+	if (!isTaken(base)) return base;
+	for (let suffix = 2; ; suffix++) {
+		const candidate = `${base}-${suffix}`;
+		if (!isTaken(candidate)) return candidate;
+	}
+}
+
+/** Format an explicit caller-supplied alias must satisfy -- the same shape generateUniqueAlias always produces. */
+export function isValidAlias(alias: string): boolean {
+	return alias.length > 0 && alias.length <= MAX_ALIAS_LENGTH && ALIAS_PATTERN.test(alias);
+}

package/src/domain/artifact.ts

@@ -15,6 +15,8 @@ export interface Artifact {
 	extra: Record<string, unknown>;
 	created_at: string;
 	updated_at: string;
+	/** Short, globally-unique, human/agent-typeable name -- see domain/artifact-alias.ts. Always present once created; the id remains the true backend identity. */
+	alias: string;
 	edges?: ArtifactEdge[];
 }
 
@@ -28,12 +30,15 @@ export interface CreateArtifactInput {
 	id?: string;
 	subtype?: string;
 	templateId?: string;
+	/** Overrides the title-derived auto-generated alias -- must be unique and match isValidAlias's format, or creation throws a real conflict/validation error. */
+	alias?: string;
 }
 
 export interface UpdateArtifactInput {
 	title?: string;
 	body?: string;
 	labels?: string[];
+	alias?: string;
 }
 
 export interface ArtifactQuery {

package/src/ops.ts

@@ -7,6 +7,7 @@ import { ARTIFACT_TRASH_RETENTION_MS, DEFAULT_STATUS_BY_KIND } from "./constants
 import type { Db } from "./db.ts";
 import { inTransaction } from "./db.ts";
 import type { Artifact, ArtifactQuery, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.ts";
+import { generateUniqueAlias, isValidAlias, slugify } from "./domain/artifact-alias.ts";
 import type { ArtifactTrashRecord } from "./domain/artifact-trash.ts";
 
 export type { ArtifactTrashRecord } from "./domain/artifact-trash.ts";
@@ -131,9 +132,27 @@ function rowToArtifact(row: Record<string, unknown>): Artifact {
 		extra: JSON.parse((row.extra as string) ?? "{}"),
 		created_at: row.created_at as string,
 		updated_at: row.updated_at as string,
+		alias: row.alias as string,
 	};
 }
 
+function isAliasTaken(db: Db, alias: string, excludeId?: string): boolean {
+	const row = excludeId
+		? db.prepare("SELECT 1 FROM artifacts WHERE alias = ? AND id != ?").get(alias, excludeId)
+		: db.prepare("SELECT 1 FROM artifacts WHERE alias = ?").get(alias);
+	return row != null;
+}
+
+/** Auto-generates a unique alias from title, or validates+reserves an explicit override. Throws a real conflict/validation error rather than silently suffixing a caller-chosen alias. */
+function resolveAlias(db: Db, title: string, explicit: string | undefined, excludeId?: string): string {
+	if (explicit === undefined) return generateUniqueAlias(slugify(title), (candidate) => isAliasTaken(db, candidate, excludeId));
+	if (!isValidAlias(explicit)) {
+		throw new Error(`"${explicit}" is not a valid alias -- lowercase letters, digits, and single hyphens only, max 50 characters`);
+	}
+	if (isAliasTaken(db, explicit, excludeId)) throw new Error(`alias "${explicit}" is already taken by another artifact`);
+	return explicit;
+}
+
 /**
  * Appends one immutable row to the generic, kind-agnostic mutation event log.
  * This is the one choke point every ArtifactStore mutation funnels through, so every
@@ -267,15 +286,21 @@ export function createArtifact(db: Db, input: CreateInput, context?: ArtifactEve
 	const extra = JSON.stringify(resolved.extra ?? {});
 	const subtype = resolved.subtype ?? "";
 	inTransaction(db, () => {
+		const alias = resolveAlias(db, resolved.title, resolved.alias);
 		const stmt = db.prepare(
-			"INSERT INTO artifacts (id, kind, title, status, subtype, body, labels, extra, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+			"INSERT INTO artifacts (id, kind, title, status, subtype, body, labels, extra, created_at, updated_at, alias) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
 		);
-		stmt.run(id, resolved.kind, resolved.title, status, subtype, resolved.body ?? "", labels, extra, now, now);
+		stmt.run(id, resolved.kind, resolved.title, status, subtype, resolved.body ?? "", labels, extra, now, now, alias);
 		appendArtifactEvent(db, { artifactId: id, type: "created", toStatus: status, ...context });
 	});
 	return getArtifact(db, id)!;
 }
 
+export function getArtifactByAlias(db: Db, alias: string): Artifact | null {
+	const row = db.prepare("SELECT * FROM artifacts WHERE alias = ?").get(alias) as Record<string, unknown> | null;
+	return row ? rowToArtifact(row) : null;
+}
+
 export function getArtifact(db: Db, id: string, opts?: { tree?: boolean; depth?: number; maxNodes?: number }): Artifact | null {
 	const row = db.prepare("SELECT * FROM artifacts WHERE id = ?").get(id) as Record<string, unknown> | null;
 	if (!row) return null;
@@ -517,11 +542,13 @@ export function updateArtifactContent(db: Db, id: string, input: UpdateArtifactI
 	if (!artifact) return null;
 	const now = new Date().toISOString();
 	inTransaction(db, () => {
-		db.prepare("UPDATE artifacts SET title = ?, body = ?, labels = ?, updated_at = ? WHERE id = ?").run(
+		const alias = input.alias === undefined ? artifact.alias : resolveAlias(db, input.title ?? artifact.title, input.alias, id);
+		db.prepare("UPDATE artifacts SET title = ?, body = ?, labels = ?, updated_at = ?, alias = ? WHERE id = ?").run(
 			input.title ?? artifact.title,
 			input.body ?? artifact.body,
 			JSON.stringify(input.labels ?? artifact.labels),
 			now,
+			alias,
 			id,
 		);
 		appendArtifactEvent(db, { artifactId: id, type: "updated", ...context });

package/src/ports/artifact-store.ts

@@ -16,6 +16,8 @@ import type { ArtifactEventContext } from "../domain/artifact-event.ts";
 export interface ArtifactStore {
 	create(input: CreateArtifactInput, context?: ArtifactEventContext): Artifact;
 	get(id: string, options?: ArtifactGraphOptions): Artifact | null;
+	/** Exact, globally-unique lookup by alias (domain/artifact-alias.ts) -- unlike title, never ambiguous, never scoped. */
+	getByAlias(alias: string): Artifact | null;
 	query(filter: ArtifactQuery): Artifact[];
 	link(link: ArtifactLink, context?: ArtifactEventContext): void;
 	/** Idempotent: removing an already-absent relationship is a no-op that returns false, not an error. */

package/src/vehicle/artifact-vehicle-shared.ts

@@ -146,7 +146,7 @@ export function matchArtifactByName(candidates: readonly Artifact[], name: strin
 	if (matches.length > 1) {
 		throw new VehicleError(
 			"artifact-name-ambiguous",
-			`${matches.length} artifacts are named "${name}": ${matches.map((a) => `${a.title} (${a.id})`).join(", ")} -- use id to disambiguate`,
+			`${matches.length} artifacts are named "${name}": ${matches.map((a) => `${a.title} (${a.alias})`).join(", ")} -- use id or alias to disambiguate`,
 			{ category: "conflict" },
 		);
 	}
@@ -154,16 +154,21 @@ export function matchArtifactByName(candidates: readonly Artifact[], name: strin
 }
 
 /**
- * Resolves a name to an id, retrying against `fetchWidened` (an unscoped/cross-project
+ * Resolves a name to an id. Checks `artifacts.getByAlias` first -- a real, indexed,
+ * globally-unique match, unlike title -- before falling back to today's scoped
+ * title-based matching, retrying against `fetchWidened` (an unscoped/cross-project
  * search) only when `fetchCandidates` finds nothing. Owns the match-or-widen control
  * flow only -- the caller supplies its own scoped/widened list calls, since scoping
  * differs per domain. Omit `fetchWidened` when there is no wider scope to retry.
  */
 export function resolveArtifactIdWidened(
+	artifacts: ArtifactStore,
 	name: string,
 	fetchCandidates: () => readonly Artifact[],
 	fetchWidened?: () => readonly Artifact[],
 ): string {
+	const byAlias = artifacts.getByAlias(name.trim());
+	if (byAlias) return byAlias.id;
 	try {
 		return matchArtifactByName(fetchCandidates(), name);
 	} catch (error) {
@@ -172,18 +177,11 @@ export function resolveArtifactIdWidened(
 	}
 }
 
-/** Synchronous equivalent of pi-papyrus's own artifactLabelsById -- server-side, a direct ArtifactStore.get() replaces the extra RPC round-trip that helper needed client-side. Disambiguates same-titled artifacts by appending their id. */
+/** Synchronous equivalent of pi-papyrus's own artifactLabelsById -- server-side, a direct ArtifactStore.get() replaces the extra RPC round-trip that helper needed client-side. Always suffixes the alias -- a short, meaningful, globally-unique reference, unlike the raw UUID it replaces. */
 export function labelsById(artifacts: ArtifactStore, ids: readonly string[]): Map<string, string> {
 	const uniqueIds = [...new Set(ids)];
 	const resolved = uniqueIds.map((id) => artifacts.get(id)).filter((artifact): artifact is Artifact => artifact !== null);
-	const titleCounts = new Map<string, number>();
-	for (const artifact of resolved) titleCounts.set(artifact.title, (titleCounts.get(artifact.title) ?? 0) + 1);
-	return new Map(
-		resolved.map((artifact) => [
-			artifact.id,
-			(titleCounts.get(artifact.title) ?? 0) > 1 ? `${artifact.title} (${artifact.id})` : artifact.title,
-		]),
-	);
+	return new Map(resolved.map((artifact) => [artifact.id, `${artifact.title} (${artifact.alias})`]));
 }
 
 export interface WorkflowRunNarrativeInput {

package/src/vehicle/discuss-vehicle.ts

@@ -49,10 +49,10 @@ function roundsTranscript(rounds: readonly DiscussionRound[]): string {
  * so there is no widened retry to attempt -- one unscoped candidate set is
  * the whole search space already.
  */
-function resolveDiscussionId(discussions: Discussions, id: unknown, name: unknown): string {
+function resolveDiscussionId(artifacts: ArtifactStore, discussions: Discussions, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
-	return resolveArtifactIdWidened(name, () => discussions.list({}));
+	return resolveArtifactIdWidened(artifacts, name, () => discussions.list({}));
 }
 
 /**
@@ -65,7 +65,7 @@ function resolveDiscussionId(discussions: Discussions, id: unknown, name: unknow
 function resolveRealTaskId(artifacts: ArtifactStore, id: unknown, name: unknown): string | undefined {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) return undefined;
-	return resolveArtifactIdWidened(name, () => artifacts.query({ kind: "task", excludeSubtype: DISCUSSION_SUBTYPE, text: name }));
+	return resolveArtifactIdWidened(artifacts, name, () => artifacts.query({ kind: "task", excludeSubtype: DISCUSSION_SUBTYPE, text: name }));
 }
 
 function resolveRealTaskIds(artifacts: ArtifactStore, ids: unknown, names: unknown): string[] | undefined {
@@ -204,7 +204,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		(input) => {
 			normalizeOptions(input);
 			defaultActorToAgent(input);
-			return { ...input, id: resolveDiscussionId(discussions, input.id, input.name) };
+			return { ...input, id: resolveDiscussionId(artifacts, discussions, input.id, input.name) };
 		},
 		(raw) => {
 			const result = raw as DiscussionAndRounds;
@@ -221,7 +221,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		"local-write",
 		{ id: stringProp, name: stringProp, reason: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
 		[],
-		(input) => ({ ...input, id: resolveDiscussionId(discussions, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveDiscussionId(artifacts, discussions, input.id, input.name) }),
 		(raw) => {
 			const artifact = raw as Artifact;
 			return { ...artifact, content: [contentBlock(artifactLine(artifact))] };
@@ -234,7 +234,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		"local-write",
 		{ id: stringProp, name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
 		[],
-		(input) => ({ ...input, id: resolveDiscussionId(discussions, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveDiscussionId(artifacts, discussions, input.id, input.name) }),
 		(raw) => {
 			const artifact = raw as Artifact;
 			return { ...artifact, content: [contentBlock(artifactLine(artifact))] };
@@ -247,7 +247,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		"local-write",
 		{ id: stringProp, name: stringProp, settlement: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
 		["settlement"],
-		(input) => ({ ...input, id: resolveDiscussionId(discussions, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveDiscussionId(artifacts, discussions, input.id, input.name) }),
 		(raw) => {
 			const artifact = raw as Artifact;
 			return { ...artifact, content: [contentBlock(artifactLine(artifact))] };
@@ -269,7 +269,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		},
 		[],
 		(input) => {
-			const discussionId = resolveDiscussionId(discussions, input.id, input.name);
+			const discussionId = resolveDiscussionId(artifacts, discussions, input.id, input.name);
 			const taskId = resolveRealTaskId(artifacts, input.task_id, input.task_name);
 			if (!taskId) throw validationError("task_id or task_name is required");
 			return { ...input, id: discussionId, task_id: taskId };
@@ -297,7 +297,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		},
 		[],
 		(input) => {
-			const discussionId = resolveDiscussionId(discussions, input.id, input.name);
+			const discussionId = resolveDiscussionId(artifacts, discussions, input.id, input.name);
 			const taskId = resolveRealTaskId(artifacts, input.task_id, input.task_name);
 			if (!taskId) throw validationError("task_id or task_name is required");
 			return { ...input, id: discussionId, task_id: taskId };
@@ -319,7 +319,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		"read",
 		{ id: stringProp, name: stringProp },
 		[],
-		(input) => ({ ...input, id: resolveDiscussionId(discussions, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveDiscussionId(artifacts, discussions, input.id, input.name) }),
 		(raw) => {
 			const result = raw as DiscussionAndRounds;
 			return { ...result, content: [contentBlock(`${artifactLine(result.discussion)}\n\n${roundsTranscript(result.rounds)}`)] };
@@ -332,7 +332,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 		"read",
 		{ id: stringProp, name: stringProp, after_round: numberProp, limit: numberProp },
 		[],
-		(input) => ({ ...input, id: resolveDiscussionId(discussions, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveDiscussionId(artifacts, discussions, input.id, input.name) }),
 		(raw) => {
 			const rounds = raw as DiscussionRound[];
 			return { rounds, content: [contentBlock(roundsTranscript(rounds))] };

package/src/vehicle/docs-vehicle.ts

@@ -32,6 +32,7 @@ function resolveDocId(
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
 	return resolveArtifactIdWidened(
+		artifacts,
 		name,
 		() => listDocuments(artifacts, scopes, { text: name, projectRoot }),
 		projectRoot === undefined ? undefined : () => listDocuments(artifacts, scopes, { text: name }),
@@ -42,7 +43,7 @@ function resolveDocId(
 function resolveTargetId(artifacts: ArtifactStore, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw validationError("target_id or target_name is required");
-	return resolveArtifactIdWidened(name, () => artifacts.query({ text: name }));
+	return resolveArtifactIdWidened(artifacts, name, () => artifacts.query({ text: name }));
 }
 
 export function registerDocsVehicleOperations(

package/src/vehicle/notes-vehicle.ts

@@ -26,17 +26,17 @@ const OWNER = "notes";
 const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
 
 /** Resolves a note's id from either an explicit id or its title within projectRoot. */
-function resolveNoteId(notes: Notes, projectRoot: string, id: unknown, name: unknown): string {
+function resolveNoteId(artifacts: ArtifactStore, notes: Notes, projectRoot: string, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
-	return resolveArtifactIdWidened(name, () => notes.list({ projectRoot, text: name }));
+	return resolveArtifactIdWidened(artifacts, name, () => notes.list({ projectRoot, text: name }));
 }
 
 /** Cross-kind equivalent for a promotion target -- a target can be a task, doc, rule, or playbook, not just a note. Unscoped by project, matching the exact behavior of the artifact.query-backed resolution it replaces. */
 function resolveArtifactId(artifacts: ArtifactStore, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw validationError("target_id or target_name is required");
-	return resolveArtifactIdWidened(name, () => artifacts.query({ text: name }));
+	return resolveArtifactIdWidened(artifacts, name, () => artifacts.query({ text: name }));
 }
 
 /**
@@ -100,7 +100,7 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 		"read",
 		{ id: stringProp, name: stringProp, project_root: stringProp },
 		["project_root"],
-		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveNoteId(artifacts, notes, input.project_root as string, input.id, input.name) }),
 	);
 
 	define(
@@ -116,7 +116,7 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 			direction: { type: "string", enum: ["asc", "desc"] },
 		},
 		["project_root"],
-		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveNoteId(artifacts, notes, input.project_root as string, input.id, input.name) }),
 	);
 
 	define(
@@ -133,7 +133,7 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 			reason: stringProp,
 		},
 		["project_root"],
-		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveNoteId(artifacts, notes, input.project_root as string, input.id, input.name) }),
 	);
 
 	define(
@@ -154,7 +154,7 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 		["project_root"],
 		(input) => ({
 			...input,
-			id: resolveNoteId(notes, input.project_root as string, input.id, input.name),
+			id: resolveNoteId(artifacts, notes, input.project_root as string, input.id, input.name),
 			target_id: resolveArtifactId(artifacts, input.target_id, input.target_name),
 		}),
 	);
@@ -174,6 +174,6 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 			reason: stringProp,
 		},
 		["project_root", "disposition"],
-		(input) => ({ ...input, id: resolveNoteId(notes, input.project_root as string, input.id, input.name) }),
+		(input) => ({ ...input, id: resolveNoteId(artifacts, notes, input.project_root as string, input.id, input.name) }),
 	);
 }

package/src/vehicle/playbooks-vehicle.ts

@@ -59,7 +59,7 @@ export interface PlaybooksVehicleDeps {
 function resolvePlaybookId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
-	return resolveArtifactIdWidened(name, () => listPlaybooks(artifacts, scopes, { text: name }));
+	return resolveArtifactIdWidened(artifacts, name, () => listPlaybooks(artifacts, scopes, { text: name }));
 }
 
 export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, deps: PlaybooksVehicleDeps): void {

package/src/vehicle/rules-vehicle.ts

@@ -33,6 +33,7 @@ function resolveRuleId(
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
 	return resolveArtifactIdWidened(
+		artifacts,
 		name,
 		() => listRules(artifacts, scopes, { text: name, projectRoot }),
 		projectRoot === undefined ? undefined : () => listRules(artifacts, scopes, { text: name }),
@@ -47,7 +48,7 @@ function resolveRuleId(
 function resolveTaskId(artifacts: ArtifactStore, _projectRoot: string | undefined, id: unknown, name: unknown): string | undefined {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) return undefined;
-	return resolveArtifactIdWidened(name, () => artifacts.query({ kind: "task", text: name }));
+	return resolveArtifactIdWidened(artifacts, name, () => artifacts.query({ kind: "task", text: name }));
 }
 
 export function registerRulesVehicleOperations(registry: VehicleRegistry, artifacts: ArtifactStore, scopes: ArtifactScopeStore): void {

package/src/vehicle/tasks-vehicle.ts

@@ -68,6 +68,7 @@ export interface TasksVehicleDeps {
  * carried, hard-won from real cross-project depend/contain friction.
  */
 function resolveTaskId(
+	artifacts: ArtifactStore,
 	tasks: Tasks,
 	filter: { projectRoot?: string; scope?: TaskViewMode; rootTaskId?: string },
 	id: unknown,
@@ -77,6 +78,7 @@ function resolveTaskId(
 	if (typeof name !== "string" || name.length === 0) throw validationError("id or name is required");
 	if (!filter.projectRoot) throw validationError("project_root is required when resolving a task by name");
 	return resolveArtifactIdWidened(
+		artifacts,
 		name,
 		() => tasks.list({ ...filter, text: name }),
 		filter.scope === undefined ? () => tasks.list({ ...filter, scope: "all", text: name }) : undefined,
@@ -84,13 +86,20 @@ function resolveTaskId(
 }
 
 /** Resolves root_task_name first and scoped to "project" only, matching the removed tool's own resolution order -- every other name lookup below must see the caller's FINAL scope/root selection, which root_task_id itself feeds into. */
-function resolveRootTaskId(tasks: Tasks, projectRoot: string | undefined, rootTaskId: unknown, rootTaskName: unknown): string | undefined {
+function resolveRootTaskId(
+	artifacts: ArtifactStore,
+	tasks: Tasks,
+	projectRoot: string | undefined,
+	rootTaskId: unknown,
+	rootTaskName: unknown,
+): string | undefined {
 	if (typeof rootTaskId === "string" && rootTaskId.length > 0) return rootTaskId;
 	if (typeof rootTaskName !== "string" || rootTaskName.length === 0) return undefined;
-	return resolveTaskId(tasks, { projectRoot, scope: "project" }, undefined, rootTaskName);
+	return resolveTaskId(artifacts, tasks, { projectRoot, scope: "project" }, undefined, rootTaskName);
 }
 
 function resolveArrayField(
+	artifacts: ArtifactStore,
 	tasks: Tasks,
 	filter: { projectRoot?: string; scope?: TaskViewMode; rootTaskId?: string },
 	ids: unknown,
@@ -98,7 +107,7 @@ function resolveArrayField(
 ): string[] | undefined {
 	if (Array.isArray(ids)) return ids as string[];
 	if (!Array.isArray(names) || names.length === 0) return undefined;
-	return names.map((entry) => resolveTaskId(tasks, filter, undefined, String(entry)));
+	return names.map((entry) => resolveTaskId(artifacts, tasks, filter, undefined, String(entry)));
 }
 
 const readSchemaProps = {
@@ -192,13 +201,13 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	/** Shared by every action taking a single id/name: resolves root_task_name first, then name -> id against the final scope. */
 	const resolveIdAndScope = (input: Record<string, unknown>): Record<string, unknown> => {
 		const projectRoot = input.project_root as string | undefined;
-		const rootTaskId = resolveRootTaskId(tasks, projectRoot, input.root_task_id, input.root_task_name);
+		const rootTaskId = resolveRootTaskId(artifacts, tasks, projectRoot, input.root_task_id, input.root_task_name);
 		const scope = input.scope as TaskViewMode | undefined;
 		const filter = { projectRoot, scope, rootTaskId };
 		return {
 			...input,
 			...(rootTaskId ? { root_task_id: rootTaskId } : {}),
-			id: resolveTaskId(tasks, filter, input.id, input.name),
+			id: resolveTaskId(artifacts, tasks, filter, input.id, input.name),
 		};
 	};
 
@@ -230,9 +239,9 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 				typeof input.parent_id === "string" && input.parent_id.length > 0
 					? input.parent_id
 					: typeof input.parent_name === "string" && input.parent_name.length > 0
-						? resolveTaskId(tasks, filter, undefined, input.parent_name)
+						? resolveTaskId(artifacts, tasks, filter, undefined, input.parent_name)
 						: undefined;
-			const dependsOn = resolveArrayField(tasks, filter, input.depends_on, input.depends_on_names);
+			const dependsOn = resolveArrayField(artifacts, tasks, filter, input.depends_on, input.depends_on_names);
 			return { ...input, ...(parentId ? { parent_id: parentId } : {}), ...(dependsOn ? { depends_on: dependsOn } : {}) };
 		},
 	);
@@ -263,7 +272,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		readSchemaProps,
 		["project_root"],
 		(input) => {
-			const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			const rootTaskId = resolveRootTaskId(artifacts, tasks, input.project_root as string, input.root_task_id, input.root_task_name);
 			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
 		},
 	);
@@ -275,7 +284,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		readSchemaProps,
 		["project_root"],
 		(input) => {
-			const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			const rootTaskId = resolveRootTaskId(artifacts, tasks, input.project_root as string, input.root_task_id, input.root_task_name);
 			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
 		},
 	);
@@ -287,7 +296,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		readSchemaProps,
 		["project_root"],
 		(input) => {
-			const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			const rootTaskId = resolveRootTaskId(artifacts, tasks, input.project_root as string, input.root_task_id, input.root_task_name);
 			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
 		},
 		(input) => {
@@ -352,7 +361,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		},
 		["project_root", "scope"],
 		(input) => {
-			const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			const rootTaskId = resolveRootTaskId(artifacts, tasks, input.project_root as string, input.root_task_id, input.root_task_name);
 			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
 		},
 	);
@@ -363,7 +372,10 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		"local-write",
 		{ id: stringProp, name: stringProp, project_root: stringProp, session_id: stringProp },
 		["project_root"],
-		(input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }),
+		(input) => ({
+			...input,
+			id: resolveTaskId(artifacts, tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
+		}),
 	);
 
 	define(
@@ -415,7 +427,10 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		"Sets the active Task Focus (singular per scope) to this Task. Multiple sessions can focus the same task while only one holds its lease.",
 		{ id: stringProp, name: stringProp, project_root: stringProp },
 		[],
-		(input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }),
+		(input) => ({
+			...input,
+			id: resolveTaskId(artifacts, tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
+		}),
 	);
 	focusOperation("pause", "Pauses the active Task Focus without clearing it.", { reason: stringProp }, [], (input) => input);
 	focusOperation("unpause", "Resumes a paused Task Focus.", {}, [], (input) => input);
@@ -588,8 +603,8 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
 			return {
 				...input,
-				id: resolveTaskId(tasks, filter, input.id, input.name),
-				dependency_id: resolveTaskId(tasks, filter, input.dependency_id, input.dependency_name),
+				id: resolveTaskId(artifacts, tasks, filter, input.id, input.name),
+				dependency_id: resolveTaskId(artifacts, tasks, filter, input.dependency_id, input.dependency_name),
 			};
 		},
 	);
@@ -612,8 +627,8 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
 			return {
 				...input,
-				id: resolveTaskId(tasks, filter, input.id, input.name),
-				dependency_id: resolveTaskId(tasks, filter, input.dependency_id, input.dependency_name),
+				id: resolveTaskId(artifacts, tasks, filter, input.id, input.name),
+				dependency_id: resolveTaskId(artifacts, tasks, filter, input.dependency_id, input.dependency_name),
 			};
 		},
 	);
@@ -636,8 +651,8 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
 			return {
 				...input,
-				parent_id: resolveTaskId(tasks, filter, input.parent_id, input.parent_name),
-				child_id: resolveTaskId(tasks, filter, input.child_id, input.child_name),
+				parent_id: resolveTaskId(artifacts, tasks, filter, input.parent_id, input.parent_name),
+				child_id: resolveTaskId(artifacts, tasks, filter, input.child_id, input.child_name),
 			};
 		},
 	);
@@ -660,8 +675,8 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
 			return {
 				...input,
-				parent_id: resolveTaskId(tasks, filter, input.parent_id, input.parent_name),
-				child_id: resolveTaskId(tasks, filter, input.child_id, input.child_name),
+				parent_id: resolveTaskId(artifacts, tasks, filter, input.parent_id, input.parent_name),
+				child_id: resolveTaskId(artifacts, tasks, filter, input.child_id, input.child_name),
 			};
 		},
 	);
@@ -682,7 +697,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		[],
 		(input) => ({
 			...input,
-			id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
+			id: resolveTaskId(artifacts, tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
 			owner: input.owner ?? input.session_id,
 		}),
 	);
@@ -700,7 +715,10 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			session_id: stringProp,
 		},
 		["owner", "token"],
-		(input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }),
+		(input) => ({
+			...input,
+			id: resolveTaskId(artifacts, tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
+		}),
 	);
 	define(
 		"release_lease",
@@ -708,7 +726,10 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		"local-write",
 		{ id: stringProp, name: stringProp, owner: stringProp, token: stringProp, project_root: stringProp, session_id: stringProp },
 		["owner", "token"],
-		(input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }),
+		(input) => ({
+			...input,
+			id: resolveTaskId(artifacts, tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
+		}),
 	);
 	define(
 		"lease",
@@ -716,7 +737,10 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		"read",
 		{ id: stringProp, name: stringProp, project_root: stringProp },
 		[],
-		(input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }),
+		(input) => ({
+			...input,
+			id: resolveTaskId(artifacts, tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name),
+		}),
 	);
 
 	define(