@zq-silk/yui 0.6.13 → 0.6.14

package/dist/repository/project.js

@@ -1,4 +1,5 @@
 import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
 /** The Yui-owned directory holding a managed Project's canonical repository. */
 export function managedProjectPath(home, projectId) {
     const id = requireIdentity(projectId, "Project id");
@@ -7,7 +8,7 @@ export function managedProjectPath(home, projectId) {
 export function createProject(id, name, path, branches, now, metadata = {}) {
     const timestamp = now.toISOString();
     return validateProject({
-        schemaVersion: 3,
+        schemaVersion: 4,
         id: requireIdentity(id, "Project id"),
         name: validateProjectName(name),
         aliases: normalizeAliases(metadata.aliases ?? [], name),
@@ -19,6 +20,7 @@ export function createProject(id, name, path, branches, now, metadata = {}) {
         stableBranch: requireGitRef(branches.stable, "Project stable branch"),
         developmentBranch: requireGitRef(branches.development, "Project development branch"),
         knowledge: [],
+        knowledgeProposals: [],
         createdAt: timestamp,
         updatedAt: timestamp
     });
@@ -26,7 +28,7 @@ export function createProject(id, name, path, branches, now, metadata = {}) {
 export function validateProjectName(value) {
     return requireIdentity(value, "Project name");
 }
-export function addProjectKnowledge(project, id, title, body, now) {
+export function addProjectKnowledge(project, id, title, body, now, provenance) {
     const timestamp = now.toISOString();
     const knowledge = {
         schemaVersion: 1,
@@ -34,6 +36,7 @@ export function addProjectKnowledge(project, id, title, body, now) {
         title: requireText(title, "Project knowledge title"),
         body: requireText(body, "Project knowledge body"),
         status: "active",
+        ...(provenance === undefined ? {} : { provenance: validateKnowledgeProvenance(provenance) }),
         createdAt: timestamp,
         updatedAt: timestamp
     };
@@ -108,6 +111,108 @@ export function retireProjectKnowledge(project, id, now) {
         throw new Error(`Project knowledge not found: ${knowledgeId}.`);
     return validateProject({ ...project, knowledge, updatedAt: now.toISOString() });
 }
+/**
+ * Stable dedup fingerprint for a promotion candidate. Two proposals with the
+ * same source identity, title, and body are the same conclusion regardless of
+ * who proposed them or when.
+ */
+export function knowledgeProposalFingerprint(input) {
+    const sourceKey = [
+        input.projectId,
+        input.source.taskId,
+        input.source.decisionId ?? "",
+        input.source.milestoneId ?? "",
+        input.source.commitSha ?? ""
+    ].join("|");
+    return createHash("sha256")
+        .update(`${sourceKey}\u0000${input.title}\u0000${input.body}`)
+        .digest("hex");
+}
+/** Digest of the cited source evidence, so a later Agent can verify it. */
+export function knowledgeEvidenceDigest(evidence) {
+    return createHash("sha256").update(requireText(evidence, "Knowledge evidence")).digest("hex");
+}
+export function findKnowledgeProposal(project, proposalId) {
+    return project.knowledgeProposals.find(({ id }) => id === proposalId) ?? null;
+}
+/**
+ * Append a validated proposal. The caller is responsible for deduplication:
+ * use {@link findKnowledgeProposalByFingerprint} first and reuse the existing
+ * pending candidate instead of storing a second copy.
+ */
+export function addKnowledgeProposal(project, proposal) {
+    const stored = validateKnowledgeProposal(proposal, project.id);
+    if (project.knowledgeProposals.some((entry) => entry.id === stored.id)) {
+        throw new Error(`Knowledge proposal already exists: ${stored.id}.`);
+    }
+    return validateProject({
+        ...project,
+        knowledgeProposals: [...project.knowledgeProposals, stored],
+        updatedAt: stored.proposedAt
+    });
+}
+export function findKnowledgeProposalByFingerprint(project, fingerprint, status) {
+    return project.knowledgeProposals.find((entry) => (entry.fingerprint === fingerprint
+        && (status === undefined || entry.status === status))) ?? null;
+}
+/** Record the Operator decision on a pending proposal. */
+export function decideKnowledgeProposal(project, proposalId, decision, now) {
+    const id = requireIdentity(proposalId, "Knowledge proposal id");
+    const timestamp = now.toISOString();
+    let found = false;
+    const knowledgeProposals = project.knowledgeProposals.map((entry) => {
+        if (entry.id !== id)
+            return entry;
+        found = true;
+        if (entry.status !== "pending") {
+            throw new Error(`Knowledge proposal is already ${entry.status}: ${id}.`);
+        }
+        return {
+            ...entry,
+            status: decision.knowledgeId === undefined ? "rejected" : "accepted",
+            decidedBy: decision.by,
+            decidedAt: timestamp,
+            ...(decision.reason === undefined ? {} : { decisionReason: requireText(decision.reason, "Knowledge proposal decision reason") }),
+            ...(decision.knowledgeId === undefined ? {} : { knowledgeId: requireIdentity(decision.knowledgeId, "Knowledge id") }),
+            updatedAt: timestamp
+        };
+    });
+    if (!found)
+        throw new Error(`Knowledge proposal not found: ${id}.`);
+    return validateProject({ ...project, knowledgeProposals, updatedAt: timestamp });
+}
+/**
+ * Pure acceptance policy. A proposal is a duplicate when an active Knowledge
+ * entry already carries its fingerprint. It conflicts when an active entry has
+ * the same title but a different conclusion; the Operator must then choose an
+ * explicit update, supersede, or reject instead of a silent overwrite.
+ */
+export function planKnowledgeAcceptance(project, proposal) {
+    const active = project.knowledge.filter((entry) => entry.status === "active");
+    const duplicate = active.find((entry) => entry.provenance?.fingerprint === proposal.fingerprint);
+    if (duplicate !== undefined)
+        return { kind: "duplicate", knowledgeId: duplicate.id };
+    const conflicting = active.find((entry) => entry.title === proposal.title);
+    if (conflicting !== undefined) {
+        throw new Error(`Knowledge ${conflicting.id} has the same title but a different conclusion.`
+            + " Accept with --update to replace its body, or reject the proposal.");
+    }
+    if (proposal.supersedesKnowledgeId !== undefined) {
+        const target = project.knowledge.find((entry) => entry.id === proposal.supersedesKnowledgeId);
+        if (target === undefined) {
+            throw new Error(`Knowledge to supersede not found: ${proposal.supersedesKnowledgeId}.`);
+        }
+        if (target.status !== "active") {
+            throw new Error(`Knowledge to supersede is not active: ${target.id}.`);
+        }
+    }
+    return {
+        kind: "create",
+        ...(proposal.supersedesKnowledgeId === undefined
+            ? {}
+            : { supersedesKnowledgeId: proposal.supersedesKnowledgeId })
+    };
+}
 export function resolveProject(projects, reference) {
     const normalized = requireText(reference, "Project reference").toLocaleLowerCase();
     const matches = projects.filter((project) => (project.id.toLocaleLowerCase() === normalized
@@ -138,8 +243,8 @@ export function assertProjectCatalog(projects) {
     }
 }
 export function validateProject(project) {
-    if (project.schemaVersion !== 3) {
-        throw new Error("Project must use schemaVersion 3.");
+    if (project.schemaVersion !== 4) {
+        throw new Error("Project must use schemaVersion 4.");
     }
     requireIdentity(project.id, "Project id");
     requireIdentity(project.name, "Project name");
@@ -172,16 +277,125 @@ export function validateProject(project) {
         if (!["active", "retired"].includes(entry.status)) {
             throw new Error("Project knowledge status is invalid.");
         }
+        if (entry.provenance !== undefined) {
+            validateKnowledgeProvenance(entry.provenance);
+        }
         requireTimestamp(entry.createdAt, "Project knowledge createdAt");
         requireTimestamp(entry.updatedAt, "Project knowledge updatedAt");
         if (knowledgeIds.has(entry.id))
             throw new Error(`Duplicate Project knowledge id: ${entry.id}.`);
         knowledgeIds.add(entry.id);
     }
+    const proposalIds = new Set();
+    for (const entry of project.knowledgeProposals) {
+        validateKnowledgeProposal(entry, project.id);
+        if (proposalIds.has(entry.id)) {
+            throw new Error(`Duplicate Knowledge proposal id: ${entry.id}.`);
+        }
+        proposalIds.add(entry.id);
+    }
     requireTimestamp(project.createdAt, "Project createdAt");
     requireTimestamp(project.updatedAt, "Project updatedAt");
     return project;
 }
+function validateKnowledgeProvenance(provenance) {
+    requireIdentity(provenance.taskId, "Knowledge provenance task id");
+    if (provenance.decisionId !== undefined) {
+        requireIdentity(provenance.decisionId, "Knowledge provenance decision id");
+    }
+    if (provenance.milestoneId !== undefined) {
+        requireIdentity(provenance.milestoneId, "Knowledge provenance milestone id");
+    }
+    if (provenance.commitSha !== undefined) {
+        requireText(provenance.commitSha, "Knowledge provenance commit");
+    }
+    if (provenance.evidenceDigest !== undefined) {
+        requireText(provenance.evidenceDigest, "Knowledge provenance evidence digest");
+    }
+    if (provenance.fingerprint !== undefined) {
+        requireText(provenance.fingerprint, "Knowledge provenance fingerprint");
+    }
+    if (provenance.proposalId !== undefined) {
+        requireIdentity(provenance.proposalId, "Knowledge provenance proposal id");
+    }
+    if (provenance.promotedBy !== undefined
+        && provenance.promotedBy !== "user"
+        && provenance.promotedBy !== "operator") {
+        throw new Error("Knowledge provenance promotedBy is invalid.");
+    }
+    if (provenance.promotedAt !== undefined) {
+        requireTimestamp(provenance.promotedAt, "Knowledge provenance promotedAt");
+    }
+    return provenance;
+}
+function validateKnowledgeProposal(proposal, projectId) {
+    if (proposal.schemaVersion !== 1) {
+        throw new Error("Knowledge proposal must use schemaVersion 1.");
+    }
+    requireIdentity(proposal.id, "Knowledge proposal id");
+    if (proposal.projectId !== projectId) {
+        throw new Error(`Knowledge proposal belongs to another Project: ${proposal.projectId}.`);
+    }
+    requireText(proposal.title, "Knowledge proposal title");
+    requireText(proposal.body, "Knowledge proposal body");
+    if (!["pending", "accepted", "rejected"].includes(proposal.status)) {
+        throw new Error("Knowledge proposal status is invalid.");
+    }
+    requireIdentity(proposal.source.taskId, "Knowledge proposal source task id");
+    if (proposal.source.decisionId !== undefined) {
+        requireIdentity(proposal.source.decisionId, "Knowledge proposal source decision id");
+    }
+    if (proposal.source.milestoneId !== undefined) {
+        requireIdentity(proposal.source.milestoneId, "Knowledge proposal source milestone id");
+    }
+    if (proposal.source.commitSha !== undefined) {
+        requireText(proposal.source.commitSha, "Knowledge proposal source commit");
+    }
+    if (proposal.scope !== undefined)
+        requireText(proposal.scope, "Knowledge proposal scope");
+    if (proposal.expiresWhen !== undefined) {
+        requireText(proposal.expiresWhen, "Knowledge proposal expiry condition");
+    }
+    if (proposal.supersedesKnowledgeId !== undefined) {
+        requireIdentity(proposal.supersedesKnowledgeId, "Knowledge proposal supersedes id");
+    }
+    requireText(proposal.fingerprint, "Knowledge proposal fingerprint");
+    if (proposal.evidenceDigest !== undefined) {
+        requireText(proposal.evidenceDigest, "Knowledge proposal evidence digest");
+    }
+    if (!["leader", "reviewer", "user", "operator"].includes(proposal.proposedBy)) {
+        throw new Error("Knowledge proposal proposedBy is invalid.");
+    }
+    requireTimestamp(proposal.proposedAt, "Knowledge proposal proposedAt");
+    if (proposal.decidedBy !== undefined
+        && proposal.decidedBy !== "user"
+        && proposal.decidedBy !== "operator") {
+        throw new Error("Knowledge proposal decidedBy is invalid.");
+    }
+    if (proposal.decidedAt !== undefined) {
+        requireTimestamp(proposal.decidedAt, "Knowledge proposal decidedAt");
+    }
+    if (proposal.decisionReason !== undefined) {
+        requireText(proposal.decisionReason, "Knowledge proposal decision reason");
+    }
+    if (proposal.knowledgeId !== undefined) {
+        requireIdentity(proposal.knowledgeId, "Knowledge proposal knowledge id");
+    }
+    requireTimestamp(proposal.updatedAt, "Knowledge proposal updatedAt");
+    if (proposal.status === "pending" && proposal.decidedAt !== undefined) {
+        throw new Error("Pending Knowledge proposal must not carry a decision timestamp.");
+    }
+    if (proposal.status !== "pending" && proposal.decidedAt === undefined) {
+        throw new Error("Decided Knowledge proposal must carry a decision timestamp.");
+    }
+    if (proposal.status === "accepted" && proposal.knowledgeId === undefined) {
+        throw new Error("Accepted Knowledge proposal must reference its Knowledge entry.");
+    }
+    if (proposal.status !== "accepted" && proposal.knowledgeId !== undefined) {
+        throw new Error("Only an accepted Knowledge proposal may reference a Knowledge entry.");
+    }
+    return proposal;
+}
 function normalizeAliases(values, name) {
     const aliases = values.map((value) => requireIdentity(value, "Project alias"));
     const folded = new Set();

package/dist/repository/taskBaseFreshness.js

@@ -0,0 +1,318 @@
+import { usageError } from "../errors/cliError.js";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { workspaceProjectEntry } from "../worktree/managedWorkspace.js";
+import { NodeGitWorkspace } from "./gitWorkspace.js";
+const COMMIT_PATTERN = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u;
+const RISK_FILE_PREVIEW = 20;
+export async function captureTaskBaseProvenance(input) {
+    const common = {
+        projectId: input.project.id,
+        directory: input.binding.directory,
+        baseRef: input.baseRef,
+        baseCommit: input.baseCommit,
+        ...(input.project.remoteUrl === undefined
+            ? {}
+            : { remoteUrl: redactRemoteUrl(input.project.remoteUrl) }),
+        remoteConfigured: input.project.remoteUrl !== undefined
+    };
+    if (input.project.remoteUrl === undefined) {
+        return { ...common, source: "not-applicable" };
+    }
+    if (input.remoteBaseline !== undefined) {
+        return {
+            ...common,
+            source: "remote-fetch",
+            trackingRef: `refs/heads/${input.remoteBaseline.branch}`,
+            trackingCommit: input.remoteBaseline.commit
+        };
+    }
+    const tracking = await input.git.inspectRemoteTracking({
+        repositoryPath: input.project.path,
+        remoteUrl: input.project.remoteUrl,
+        branch: input.project.developmentBranch
+    });
+    if (tracking === null) {
+        return { ...common, source: "unknown" };
+    }
+    return {
+        ...common,
+        source: "local-tracking",
+        trackingRef: tracking.ref,
+        trackingCommit: tracking.commit
+    };
+}
+export function recordTaskBaseProvenanceEvents(tx, taskId, provenance, now) {
+    for (const entry of provenance) {
+        const payload = {
+            projectId: entry.projectId,
+            directory: entry.directory,
+            baseRef: entry.baseRef,
+            baseCommit: entry.baseCommit,
+            source: entry.source,
+            remoteConfigured: entry.remoteConfigured ? "true" : "false",
+            ...(entry.remoteUrl === undefined ? {} : { remoteUrl: entry.remoteUrl }),
+            ...(entry.trackingRef === undefined ? {} : { trackingRef: entry.trackingRef }),
+            ...(entry.trackingCommit === undefined ? {} : { trackingCommit: entry.trackingCommit })
+        };
+        tx.saveEvent(taskId, createTaskEvent(tx.nextEventId(taskId), taskId, "task.base-provenance", payload, now));
+    }
+}
+export async function inspectTaskBaseFreshness(taskId, store, options = {}) {
+    const task = requireTask(store, taskId);
+    const git = options.git ?? newGitWorkspace();
+    const workspace = store.getTaskWorkspace(taskId);
+    const entries = await Promise.all(task.projectBindings.map(async (binding) => {
+        const project = requireProject(store, binding.projectId);
+        const entry = workspace === null ? undefined : workspaceProjectEntry(workspace, project.id);
+        const baseCommit = await resolveBaseCommit(git, project, binding, entry);
+        const workspacePath = entry?.path ?? project.path;
+        const provenance = latestBaseProvenance(store.listEvents(taskId), project.id);
+        const tracked = await resolveTracked(git, project, workspacePath, options.refresh === true);
+        const status = await classifyStatus(git, workspacePath, project, baseCommit, tracked);
+        const remoteOnlyChangedFiles = await remoteOnlyChanges(git, workspacePath, status, baseCommit, tracked?.commit);
+        const workspaceClean = await inspectWorkspaceClean(git, workspacePath);
+        return {
+            projectId: project.id,
+            directory: binding.directory,
+            baseRef: binding.baseRef,
+            baseCommit,
+            status,
+            source: tracked?.source ?? (project.remoteUrl === undefined ? "not-applicable" : "compatibility-projection"),
+            workspacePath,
+            workspaceClean,
+            ...(tracked === undefined ? {} : {
+                trackedRef: tracked.ref,
+                trackedCommit: tracked.commit,
+                ...(tracked.error === undefined ? {} : { error: redactText(tracked.error) })
+            }),
+            remoteOnlyChangedFiles: remoteOnlyChangedFiles.files.slice(0, RISK_FILE_PREVIEW),
+            remoteOnlyChangedFileCount: remoteOnlyChangedFiles.files.length,
+            ...(risk(status, workspaceClean, remoteOnlyChangedFiles.files, tracked?.error) === undefined
+                ? {}
+                : { risk: risk(status, workspaceClean, remoteOnlyChangedFiles.files, tracked?.error) }),
+            ...(provenance === undefined ? {} : {
+                observedAt: provenance.event.createdAt,
+                observedSource: provenance.provenance.source,
+                ...(provenance.provenance.remoteUrl === undefined
+                    ? {}
+                    : { observedRemoteUrl: provenance.provenance.remoteUrl }),
+                ...(provenance.provenance.trackingRef === undefined
+                    ? {}
+                    : { observedTrackingRef: provenance.provenance.trackingRef }),
+                ...(provenance.provenance.trackingCommit === undefined
+                    ? {}
+                    : { observedTrackingCommit: provenance.provenance.trackingCommit })
+            })
+        };
+    }));
+    return { taskId, refreshed: options.refresh === true, entries };
+}
+export function assertTaskBaseFreshnessForCompletion(report) {
+    const warnings = [];
+    for (const entry of report.entries) {
+        if (entry.status === "behind" || entry.status === "diverged") {
+            throw usageError(`Task ${report.taskId} Project ${entry.projectId} base is ${entry.status}; `
+                + `run 'yui task base status ${report.taskId} --refresh' and choose an explicit delivery base. `
+                + "Safe resolutions are to rebase or merge the Task workspace onto the refreshed remote base, "
+                + "create a clean delivery branch from that base and cherry-pick the Task changes, "
+                + "or ask the Leader to resolve it. Continuing without rebasing is allowed only after explicitly "
+                + "recording the unrelated-diff risk.");
+        }
+        if (entry.workspaceClean === false) {
+            throw usageError(`Task ${report.taskId} Project ${entry.projectId} workspace is dirty; `
+                + "commit, integrate, or clean it before completion.");
+        }
+        if (entry.status === "unknown") {
+            if (report.refreshed) {
+                throw usageError(`Task ${report.taskId} Project ${entry.projectId} remote base could not be refreshed: `
+                    + `${entry.error ?? "unknown error"}`);
+            }
+            warnings.push(`Project ${entry.projectId} remote base is unknown; local completion continues without a remote claim.`);
+        }
+    }
+    return warnings;
+}
+export function renderTaskBaseFreshnessReport(report) {
+    if (report.entries.length === 0) {
+        return `Task ${report.taskId} has no Projects.\n`;
+    }
+    const lines = [
+        `Task base freshness: ${report.taskId} (source: ${report.refreshed ? "remote refresh" : "local tracking"})`
+    ];
+    for (const entry of report.entries) {
+        lines.push(`- ${entry.directory}: ${entry.projectId} @ ${entry.baseCommit}`, `  status: ${entry.status}; workspace: ${entry.workspaceClean === null ? "unknown" : entry.workspaceClean ? "clean" : "dirty"}`, `  observed remote: ${entry.observedRemoteUrl ?? "-"}`, `  tracked: ${entry.trackedCommit ?? "-"}${entry.trackedRef === undefined ? "" : ` (${entry.trackedRef})`}`, `  observed: ${entry.observedTrackingCommit ?? "-"}${entry.observedAt === undefined ? "" : ` at ${entry.observedAt}`}`);
+        if (entry.risk !== undefined)
+            lines.push(`  risk: ${entry.risk}`);
+        if (entry.error !== undefined)
+            lines.push(`  error: ${entry.error}`);
+    }
+    return lines.join("\n").concat("\n");
+}
+function newGitWorkspace() {
+    return new NodeGitWorkspace();
+}
+function requireTask(store, taskId) {
+    const task = store.getTask(taskId);
+    if (task === null)
+        throw usageError(`Task not found: ${taskId}.`);
+    return task;
+}
+function requireProject(store, projectId) {
+    const project = store.getProject(projectId);
+    if (project === null)
+        throw usageError(`Project not found: ${projectId}.`);
+    return project;
+}
+async function resolveBaseCommit(git, project, binding, entry) {
+    if (entry?.baseCommit !== undefined)
+        return entry.baseCommit;
+    if (COMMIT_PATTERN.test(binding.baseRef))
+        return binding.baseRef.toLowerCase();
+    return (await git.inspect(project.path, binding.baseRef)).baseCommit;
+}
+async function resolveTracked(git, project, workspacePath, refresh) {
+    if (project.remoteUrl === undefined)
+        return undefined;
+    if (refresh) {
+        if (git.fetchRemoteHeadIntoWorktree === undefined) {
+            return {
+                ref: `refs/heads/${project.developmentBranch}`,
+                commit: "",
+                source: "remote-refresh",
+                error: "managed Git workspace does not support remote refresh"
+            };
+        }
+        try {
+            const remote = await git.fetchRemoteHeadIntoWorktree({
+                repositoryPath: workspacePath,
+                remoteUrl: project.remoteUrl,
+                branch: project.developmentBranch
+            });
+            return {
+                ref: `refs/heads/${remote.branch}`,
+                commit: remote.commit,
+                source: "remote-refresh"
+            };
+        }
+        catch (error) {
+            return {
+                ref: `refs/heads/${project.developmentBranch}`,
+                commit: "",
+                source: "remote-refresh",
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    const tracking = await git.inspectRemoteTracking({
+        repositoryPath: project.path,
+        remoteUrl: project.remoteUrl,
+        branch: project.developmentBranch
+    });
+    if (tracking === null)
+        return undefined;
+    return { ref: tracking.ref, commit: tracking.commit, source: "local-tracking" };
+}
+async function classifyStatus(git, repositoryPath, project, baseCommit, tracked) {
+    if (project.remoteUrl === undefined)
+        return "not-applicable";
+    if (tracked === undefined || tracked.commit === "")
+        return "unknown";
+    if (tracked.commit === baseCommit)
+        return "up-to-date";
+    if (await git.isAncestor(repositoryPath, baseCommit, tracked.commit)) {
+        return "behind";
+    }
+    if (await git.isAncestor(repositoryPath, tracked.commit, baseCommit)) {
+        return "ahead";
+    }
+    return "diverged";
+}
+async function remoteOnlyChanges(git, repositoryPath, status, baseCommit, trackedCommit) {
+    if (trackedCommit === undefined
+        || trackedCommit === ""
+        || (status !== "behind" && status !== "diverged")) {
+        return { files: [] };
+    }
+    try {
+        const fromCommit = status === "behind"
+            ? baseCommit
+            : await git.mergeBase({ repositoryPath, leftCommit: baseCommit, rightCommit: trackedCommit });
+        return {
+            files: await git.changedFilesBetween({ repositoryPath, fromCommit, toCommit: trackedCommit })
+        };
+    }
+    catch {
+        return { files: [] };
+    }
+}
+async function inspectWorkspaceClean(git, workspacePath) {
+    try {
+        return await git.isClean(workspacePath);
+    }
+    catch {
+        return null;
+    }
+}
+function risk(status, workspaceClean, files, error) {
+    if (status === "behind" || status === "diverged") {
+        const suffix = files.length === 0
+            ? "no remote-only file delta is locally provable"
+            : `${files.length} remote-only file${files.length === 1 ? "" : "s"} (${files.slice(0, RISK_FILE_PREVIEW).join(", ")}${files.length > RISK_FILE_PREVIEW ? ", ..." : ""}) may appear as unrelated delivery diff`;
+        return `base is ${status}; ${suffix}.`;
+    }
+    if (workspaceClean === false)
+        return "worktree has uncommitted changes.";
+    if (status === "unknown")
+        return error === undefined ? "remote identity is not locally observable." : redactText(error);
+    return undefined;
+}
+function latestBaseProvenance(events, projectId) {
+    const event = [...events].reverse().find((candidate) => (candidate.type === "task.base-provenance" && candidate.payload.projectId === projectId));
+    if (event === undefined)
+        return undefined;
+    const source = event.payload.source;
+    if (source !== "local-tracking"
+        && source !== "remote-fetch"
+        && source !== "unknown"
+        && source !== "not-applicable") {
+        return undefined;
+    }
+    return {
+        event,
+        provenance: {
+            projectId,
+            directory: event.payload.directory ?? "",
+            baseRef: event.payload.baseRef ?? "",
+            baseCommit: event.payload.baseCommit ?? "",
+            source,
+            remoteConfigured: event.payload.remoteConfigured === "true",
+            ...(event.payload.remoteUrl === undefined ? {} : { remoteUrl: event.payload.remoteUrl }),
+            ...(event.payload.trackingRef === undefined ? {} : { trackingRef: event.payload.trackingRef }),
+            ...(event.payload.trackingCommit === undefined ? {} : { trackingCommit: event.payload.trackingCommit })
+        }
+    };
+}
+function redactText(value) {
+    return redactRemoteUrl(value);
+}
+export function redactRemoteUrl(value) {
+    return value
+        .replace(ABSOLUTE_REMOTE_URL_PATTERN, redactAbsoluteRemoteUrl)
+        .replace(SCP_REMOTE_URL_PATTERN, (_match, prefix, _user, host, path) => `${prefix}redacted@${host}:${path}`);
+}
+const ABSOLUTE_REMOTE_URL_PATTERN = /[A-Za-z][A-Za-z0-9+.-]*:\/\/[^\s"'<>]+/gu;
+const SCP_REMOTE_URL_PATTERN = /(^|[\s"'(])([A-Za-z0-9._-]+)@([A-Za-z0-9.-]+):([^\s"'<>]+)/gu;
+function redactAbsoluteRemoteUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.username !== "" || url.password !== "") {
+            url.username = "redacted";
+            url.password = "";
+            return url.toString();
+        }
+        return value;
+    }
+    catch {
+        return value.replace(/^([A-Za-z][A-Za-z0-9+.-]*:\/\/)[^/@\s]+@/u, "$1redacted@");
+    }
+}

package/dist/repository/taskWorkspacePreparer.js

@@ -14,6 +14,7 @@ import { NodeGitWorkspace, worktreeIdentity } from "./gitWorkspace.js";
 import { acquireProjectMaintenanceLocks } from "./projectMaintenanceLock.js";
 import { generateTaskWorkspaceIdentity, isLegacyTaskRef, taskArchiveRef, taskMainBranch, taskWorkspaceRefSegment, taskWorkspaceRefSegmentFromIdentity, TASK_WORKSPACE_TOKEN_PATTERN, validateTaskWorkspaceIdentity } from "./taskWorkspaceIdentity.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
+import { captureTaskBaseProvenance, recordTaskBaseProvenanceEvents } from "./taskBaseFreshness.js";
 const MAIN_WORKTREE = "main";
 const LEADER_ROLE = "leader";
 /**
@@ -240,7 +241,8 @@ export class FileTaskWorkspacePreparer {
                         baseRef: remote.commit,
                         recordedBaseRef: remote.commit,
                         expectedCommit: remote.commit,
-                        pinTask: true
+                        pinTask: true,
+                        remoteBaseline: remote
                     });
                     continue;
                 }
@@ -270,6 +272,14 @@ export class FileTaskWorkspacePreparer {
                     && physical.baseCommit !== baseline.expectedCommit) {
                     throw new Error(`Task Project workspace did not start at the fetched remote baseline: ${project.id}.`);
                 }
+                const provenance = await captureTaskBaseProvenance({
+                    git: this.git,
+                    project,
+                    binding,
+                    baseRef: previous?.baseRef ?? baseline.recordedBaseRef,
+                    baseCommit: physical.baseCommit,
+                    ...(baseline.remoteBaseline === undefined ? {} : { remoteBaseline: baseline.remoteBaseline })
+                });
                 prepared.push({
                     project,
                     entry: {
@@ -280,7 +290,8 @@ export class FileTaskWorkspacePreparer {
                         branch: physical.branch,
                         baseRef: previous?.baseRef ?? baseline.recordedBaseRef,
                         baseCommit: physical.baseCommit
-                    }
+                    },
+                    provenance
                 });
             }
             await ensureWorkspaceView(root, prepared.map(({ entry }) => entry));
@@ -351,6 +362,9 @@ export class FileTaskWorkspacePreparer {
                     tx.saveTask(persistedTask);
                 }
                 tx.saveManagedWorkspace(preserveWorkspaceCreatedAt(workspace, current));
+                if (current === null) {
+                    recordTaskBaseProvenanceEvents(tx, task.id, prepared.map(({ provenance }) => provenance), timestamp);
+                }
                 for (const role of tx.listRoles(task.id)) {
                     // The Role field is only a cwd/snapshot hint.  Preserve the hint for
                     // an active WorkItem assignment; the durable owner is the WorkItem,