@mingchuno/agent-workflows 0.2.0 → 0.3.0

package/dist/src/tui/views.js

@@ -1,7 +1,167 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from "ink";
+import stringWidth from "string-width";
 import { recoveryUnavailable } from "../recovery.js";
 import { cells, colorFor, duration, elapsedRun, executionDuration, wrapLines, } from "./format.js";
+// The detail panel contributes four columns of border and padding.
+const detailWideBreakpoint = 136;
+const detailLabelWidth = 19;
+const hangingLabelMarker = "\u{e000}";
+const conciseErrorWidth = 120;
+const detailColumnGap = " │ ";
+function localTimestamp(value) {
+    if (!value)
+        return "not recorded";
+    const date = new Date(value);
+    if (!Number.isFinite(date.valueOf()))
+        return "unavailable";
+    return new Intl.DateTimeFormat(undefined, {
+        dateStyle: "medium",
+        timeStyle: "medium",
+    }).format(date);
+}
+function profileValue(value, key) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const candidate = value[key];
+    return typeof candidate === "string" && candidate ? candidate : undefined;
+}
+function readableProfile(value, fallbackProvider) {
+    return [
+        profileValue(value, "provider") ??
+            fallbackProvider ??
+            "provider unavailable",
+        profileValue(value, "model") ?? "model unavailable",
+        profileValue(value, "reasoningEffort") ?? "reasoning unavailable",
+    ].join(" / ");
+}
+function sameProfile(requested, effective, provider) {
+    return (readableProfile(requested, provider) ===
+        readableProfile(effective, provider));
+}
+function json(value) {
+    return JSON.stringify(value) ?? "unavailable";
+}
+function conciseError(run) {
+    const error = run.error ?? run.executions?.at(-1)?.error;
+    if (!error)
+        return run.outcome === "cancelled"
+            ? "Run was cancelled."
+            : run.outcome === "blocked"
+                ? "Run is blocked."
+                : "Run requires operator attention.";
+    const firstLine = error.split("\n", 1)[0].replace(/^Error:\s*/i, "");
+    const summary = cells(firstLine, conciseErrorWidth);
+    return cells(firstLine, conciseErrorWidth + 1) === summary
+        ? summary
+        : `${cells(firstLine, conciseErrorWidth - 1)}…`;
+}
+function label(label, value) {
+    return `${hangingLabelMarker}${label.padEnd(detailLabelWidth)}${value}`;
+}
+export function wrapDetailLines(lines, width) {
+    return lines.flatMap((line) => {
+        if (!line.startsWith(hangingLabelMarker))
+            return wrapLines([line], width);
+        const content = line.slice(hangingLabelMarker.length);
+        const prefix = content.slice(0, detailLabelWidth);
+        const value = content.slice(detailLabelWidth);
+        const wrappedValue = wrapLines([value], Math.max(1, width - detailLabelWidth));
+        return wrappedValue.map((part, index) => index === 0
+            ? `${prefix}${part}`
+            : `${" ".repeat(detailLabelWidth)}${part}`);
+    });
+}
+function validationLines(run, now) {
+    return [
+        "VALIDATION",
+        ...(run.validation?.length
+            ? run.validation.flatMap((check) => [
+                `${check.command} ${check.args.join(" ")} · exit ${check.exitCode} · ${duration(check.startedAt, check.finishedAt, now)}`,
+            ])
+            : ["not recorded"]),
+    ];
+}
+function validationSummary(run) {
+    const checks = run.validation ?? [];
+    if (!checks.length)
+        return "not recorded";
+    const successful = checks.filter((check) => check.exitCode === 0).length;
+    const failed = checks.length - successful;
+    return [
+        `${checks.length} recorded`,
+        successful ? `${successful} exit 0` : "",
+        failed ? `${failed} nonzero` : "",
+    ]
+        .filter(Boolean)
+        .join(" · ");
+}
+function sessionLines(sessions, now) {
+    return [
+        "AGENT SESSIONS",
+        ...(sessions.length
+            ? sessions.flatMap((session) => {
+                const effective = readableProfile(session.effective, session.provider);
+                const profile = sameProfile(session.requested, session.effective, session.provider)
+                    ? `Effective ${effective}`
+                    : `Requested ${readableProfile(session.requested, session.provider)} → Effective ${effective}`;
+                return [
+                    `${session.step} · invocation ${session.attempt} · ${session.outcome} · ${duration(session.startedAt, session.finishedAt, now)}`,
+                    profile,
+                ];
+            })
+            : ["not recorded"]),
+    ];
+}
+function executionLines(run, now) {
+    const executions = [...(run.executions ?? [])].reverse();
+    if (!executions.length)
+        return ["CURRENT EXECUTION", "not started"];
+    return executions.flatMap((execution, index) => {
+        const executionTime = execution.startedAt
+            ? executionDuration(execution, now).replace("—", "unavailable")
+            : "not started";
+        const queueWait = duration(execution.createdAt, execution.startedAt ?? execution.finishedAt, now);
+        const recovery = execution.recoveryOf
+            ? [
+                label("Recovery", "continued from prior execution"),
+                label("Recovery gap", duration(run.executions?.find((candidate) => candidate.id === execution.recoveryOf)?.finishedAt, execution.createdAt, now).replace("—", "unavailable")),
+                label("Reused steps", execution.reusedSteps?.length
+                    ? execution.reusedSteps.join(", ")
+                    : "none recorded"),
+            ]
+            : [];
+        const lines = index === 0
+            ? [
+                "CURRENT EXECUTION",
+                label("Outcome", execution.outcome),
+                label("Phase", execution.phase),
+                label("Execution duration", executionTime),
+                label("Queue wait", queueWait),
+                label("Created", localTimestamp(execution.createdAt)),
+                label("Started", localTimestamp(execution.startedAt)),
+                label("Finished", localTimestamp(execution.finishedAt)),
+                ...recovery,
+            ]
+            : [
+                `PRIOR EXECUTION ${executions.length - index}`,
+                `${execution.outcome} · ${execution.phase} · duration ${executionTime} · queue ${queueWait}`,
+                `${localTimestamp(execution.startedAt)} → ${localTimestamp(execution.finishedAt)}`,
+                ...recovery,
+            ];
+        return index < executions.length - 1 ? [...lines, ""] : lines;
+    });
+}
+function padToWidth(value, width) {
+    return `${value}${" ".repeat(Math.max(0, width - stringWidth(value)))}`;
+}
+function composeDetailColumns(left, right, width) {
+    const leftWidth = Math.floor((width - detailColumnGap.length) * 0.58);
+    const rightWidth = width - leftWidth - detailColumnGap.length;
+    const leftLines = wrapDetailLines(left, leftWidth);
+    const rightLines = wrapDetailLines(right, rightWidth);
+    return Array.from({ length: Math.max(leftLines.length, rightLines.length) }, (_, index) => `${padToWidth(leftLines[index] ?? "", leftWidth)}${detailColumnGap}${rightLines[index] ?? ""}`);
+}
 function stepText(event) {
     if (!event)
         return "No steps recorded";
@@ -38,56 +198,126 @@ export function summaryLines(run, now, event) {
         ...(run.change ? [`Change request: ${run.change.url}`] : []),
     ];
 }
-export function detailLines(run, sessions, now, recoveryReason = recoveryUnavailable(run)) {
-    return [
-        `#${run.issue.number} ${run.issue.title}`,
-        `${run.outcome} · ${run.phase} · attempt ${run.attempt}`,
-        `Run: ${run.id}`,
-        `Branch: ${run.branch}`,
-        `Issue: ${run.issue.url}`,
-        `Total elapsed: ${elapsedRun(run, now)}`,
-        ...(run.executions ?? []).flatMap((execution, index) => [
+export function detailLines(run, sessions, now, recoveryReason = recoveryUnavailable(run), width = 76, available = {
+    stop: false,
+    retry: false,
+    recover: false,
+}) {
+    const validation = validationSummary(run);
+    const recovery = run.outcome === "failed"
+        ? recoveryReason
+            ? "restricted"
+            : "eligible"
+        : "not applicable";
+    const attention = ["failed", "blocked", "cancelled"].includes(run.outcome)
+        ? [
+            "",
+            "ATTENTION",
+            label("Problem", conciseError(run)),
+            label("Recovery", recoveryReason ?? "Eligible; runner checks still apply"),
+            label("Action", [
+                available.recover ? "c recover" : "",
+                available.retry ? "r retry" : "",
+                available.stop ? "s stop" : "",
+            ]
+                .filter(Boolean)
+                .join(" · ") || "none available"),
+        ]
+        : [];
+    const executions = executionLines(run, now);
+    const evidence = [
+        ...validationLines(run, now),
+        "",
+        ...sessionLines(sessions, now),
+    ];
+    const evidenceArea = width >= detailWideBreakpoint
+        ? composeDetailColumns(executions, evidence, width)
+        : [...executions, "", ...evidence];
+    const executionsByRecency = [...(run.executions ?? [])].reverse();
+    const executionErrors = executionsByRecency.filter((execution) => execution.error);
+    const diagnostics = run.error || executionErrors.length
+        ? [
+            "",
+            "DIAGNOSTICS",
+            ...(run.error ? [label("Run error", run.error)] : []),
+            ...executionErrors.map((execution, index) => label(index === 0 ? "Current error" : "Prior error", execution.error)),
+        ]
+        : [];
+    const technical = [
+        "",
+        "TECHNICAL DETAILS",
+        label("Run ID", run.id),
+        label("Issue URL", run.issue.url || "unavailable"),
+        label("Checkout", run.checkout || "unavailable"),
+        label("Task key", run.taskKey),
+        label("Created ISO", run.createdAt),
+        label("Updated ISO", run.updatedAt),
+        ...(run.retryOf ? [label("Retry of", run.retryOf)] : []),
+        ...(run.base ? [label("Base revision", run.base)] : []),
+        ...(run.head ? [label("Head revision", run.head)] : []),
+        ...(run.change ? [label("Change URL", run.change.url)] : []),
+        ...executionsByRecency.flatMap((execution, index) => [
             "",
-            `EXECUTION ${index + 1}: ${execution.id}`,
-            `${execution.outcome} · ${execution.phase} · duration ${executionDuration(execution, now)}`,
-            `Queue wait: ${duration(execution.createdAt, execution.startedAt ?? execution.finishedAt, now)}`,
-            `Started: ${execution.startedAt ?? "Not started"} · Finished: ${execution.finishedAt ?? "—"}`,
+            `Execution ${executionsByRecency.length - index}`,
+            label("Execution ID", execution.id),
+            label("Created ISO", execution.createdAt),
+            label("Started ISO", execution.startedAt ?? "not recorded"),
+            label("Finished ISO", execution.finishedAt ?? "not recorded"),
             ...(execution.recoveryOf
-                ? [
-                    `Recovered from: ${execution.recoveryOf}`,
-                    `Reused: ${execution.reusedSteps?.join(", ") ?? "—"}`,
-                ]
+                ? [label("Recovery source", execution.recoveryOf)]
                 : []),
         ]),
-        "",
-        "RECOVERY",
-        recoveryReason ?? "Eligible for admission; runner checks still required",
-        "",
-        "ERROR",
-        run.error ?? "None",
-        "",
-        "VALIDATION",
-        ...(run.validation?.flatMap((check) => [
-            `${check.command} ${check.args.join(" ")} · exit ${check.exitCode} · ${duration(check.startedAt, check.finishedAt, now)}`,
-            `Log: ${check.log}`,
-        ]) ?? ["No checks recorded"]),
-        "",
-        "AGENT SESSIONS",
-        ...sessions.flatMap((session) => [
-            `${session.step} · invocation ${session.attempt} · ${session.outcome}`,
-            `Session: ${session.sessionId ?? session.sessionState}`,
-            `Duration: ${duration(session.startedAt, session.finishedAt, now)}`,
-            `Requested: ${JSON.stringify(session.requested)}`,
-            `Effective: ${JSON.stringify(session.effective)}`,
-            `Log: ${session.log}`,
+        ...(run.validation?.flatMap((check, index) => [
             "",
+            `Validation ${index + 1}`,
+            label("Log path", check.log),
+            label("Started ISO", check.startedAt),
+            label("Finished ISO", check.finishedAt),
+        ]) ?? []),
+        ...sessions.flatMap((session, index) => [
+            "",
+            `Agent session ${index + 1}`,
+            label("Invocation ID", session.id),
+            label("Session ID", session.sessionId ?? session.sessionState),
+            label("Provider", session.provider),
+            label("Log path", session.log),
+            label("Started ISO", session.startedAt),
+            label("Finished ISO", session.finishedAt ?? "not recorded"),
+            label("Requested profile", json(session.requested)),
+            label("Effective profile", json(session.effective)),
         ]),
     ];
+    return [
+        `#${run.issue.number} ${run.issue.title}`,
+        label("Outcome", run.outcome),
+        label("Phase", run.phase),
+        label("Attempt", String(run.attempt)),
+        label("Total elapsed", elapsedRun(run, now).replace("—", "unavailable")),
+        label("Branch", run.branch || "unavailable"),
+        label("Health", `Error ${run.error || run.executions?.some((execution) => execution.error) ? "recorded" : "none"} · Validation ${validation} · Recovery ${recovery}`),
+        ...attention,
+        "",
+        ...evidenceArea,
+        ...diagnostics,
+        ...technical,
+    ];
 }
-export function Lines({ lines, width, height, offset = 0, }) {
-    const wrapped = wrapLines(lines, width);
+export function Lines({ lines, width, height, offset = 0, outcome, }) {
+    const wrapped = wrapDetailLines(lines, width);
     const start = Math.min(offset, Math.max(0, wrapped.length - height));
-    return (_jsx(Box, { flexDirection: "column", width: width, height: height, overflow: "hidden", children: wrapped.slice(start, start + height).map((line, index) => (_jsx(Box, { height: 1, flexShrink: 0, children: _jsx(Text, { wrap: "truncate", children: line || " " }) }, `${start + index}`))) }));
+    const summaryOutcomeIndex = wrapped.findIndex((line) => line.startsWith("Outcome"));
+    return (_jsx(Box, { flexDirection: "column", width: width, height: height, overflow: "hidden", children: wrapped.slice(start, start + height).map((line, index) => {
+            const absoluteIndex = start + index;
+            const divider = line.indexOf(detailColumnGap);
+            const left = divider >= 0 ? line.slice(0, divider) : line;
+            const right = divider >= 0
+                ? line.slice(divider + detailColumnGap.length)
+                : undefined;
+            const isHeading = (value) => /^[A-Z][A-Z0-9 ]+$/.test(value.trim());
+            return (_jsx(Box, { height: 1, flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: absoluteIndex === summaryOutcomeIndex
+                        ? colorFor(outcome ?? "")
+                        : undefined, children: [_jsx(Text, { bold: isHeading(left), children: left || " " }), right !== undefined ? (_jsxs(_Fragment, { children: [_jsx(Text, { children: detailColumnGap }), _jsx(Text, { bold: isHeading(right), children: right })] })) : null] }) }, `${absoluteIndex}`));
+        }) }));
 }
 export function RunList({ runs, selected, width, height, now, }) {
     const count = Math.max(1, Math.floor(height / 3));

package/dist/src/workspace.js

@@ -3,6 +3,12 @@ import { access, lstat, mkdir, readFile, realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { BlockedError, } from "./domain.js";
 import { command } from "./runtime/process.js";
+function fileStateDigest(content, mode) {
+    return createHash("sha256")
+        .update(content)
+        .update(String(mode))
+        .digest("hex");
+}
 export class ExistingCheckout {
     processDirectories = new Map();
     processDirectory(project) {
@@ -97,7 +103,7 @@ export class ExistingCheckout {
                 if (stat.isSymbolicLink())
                     throw new BlockedError(`Changed symlink requires manual handling: ${path}`);
                 const content = await readFile(absolute);
-                files[path] = createHash("sha256").update(content).digest("hex");
+                files[path] = fileStateDigest(content, stat.mode);
                 hash.update(path).update(content).update(String(stat.mode));
                 if (untracked.split("\0").includes(path))
                     fullDiff += `\n--- /dev/null\n+++ b/${path}\n${content.toString()}`;
@@ -125,12 +131,19 @@ export class ExistingCheckout {
     }
     async commit(project, expected, publication, runId, signal) {
         signal?.throwIfAborted();
+        const runMarkers = publication.commitMessage
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.startsWith("Agent-Workflows-Run:"));
+        if (runMarkers.length !== 1 ||
+            runMarkers[0] !== `Agent-Workflows-Run: ${runId}`)
+            throw new BlockedError("Commit message must contain exactly one matching workflow run marker");
         const current = await this.inspect(project);
         if (current.head !== expected.head) {
             const message = await this.git(project, "log", "-1", "--format=%B");
             const parent = await this.git(project, "rev-parse", "HEAD^");
             if (parent === expected.head &&
-                message.includes(`Agent-Workflows-Run: ${runId}`) &&
+                message.trimEnd() === publication.commitMessage.trimEnd() &&
                 current.paths.length === 0) {
                 const changed = (await this.git(project, "diff", "HEAD^", "HEAD", "--no-renames", "--name-only", "-z"))
                     .split("\0")
@@ -139,7 +152,11 @@ export class ExistingCheckout {
                 if (JSON.stringify(changed) !== JSON.stringify(expected.paths))
                     throw new BlockedError("Reconciled commit has an unexpected change set");
                 for (const [path, digest] of Object.entries(expected.files)) {
-                    const actual = await readFile(join(project.checkout, path)).then((content) => createHash("sha256").update(content).digest("hex"), (error) => {
+                    const absolute = join(project.checkout, path);
+                    const actual = await Promise.all([
+                        readFile(absolute),
+                        lstat(absolute),
+                    ]).then(([content, stat]) => fileStateDigest(content, stat.mode), (error) => {
                         if (error.code === "ENOENT")
                             return null;
                         throw error;
@@ -156,15 +173,11 @@ export class ExistingCheckout {
             throw new BlockedError("No changes to commit");
         await this.runGit(project, ["add", "--", ...expected.paths], { signal });
         await this.runGit(project, [
-            "-c",
-            `user.name=${project.gitIdentity.name}`,
-            "-c",
-            `user.email=${project.gitIdentity.email}`,
             "-c",
             "core.hooksPath=/dev/null",
             "commit",
             "-m",
-            `${publication.commitMessage}\n\nAgent-Workflows-Run: ${runId}`,
+            publication.commitMessage,
         ], { signal });
         return this.git(project, "rev-parse", "HEAD");
     }

package/docs/api.md

@@ -4,7 +4,13 @@ Exports are in `src/index.ts`; the built package resolves to `dist/src/index.js`
 
 ## Runner and controls
 
-`new Runner({config,databaseUrl,hosting,agents,workspace?,workflow?,workflowVersion?,promptBaseDirectory?})` injects hosting/agent adapters and optionally a workspace strategy or workflow. `hosting(project)` returns a host-qualified adapter. `agents` maps provider names to adapters. The default workspace uses the existing checkout. One DBOS runtime runs per Node process; one runner owns each configuration and checkout.
+`new Runner({config,databaseUrl,hosting,agents,workspace?,workflow?,workflowVersion?,pathBaseDirectory?,promptBaseDirectory?})` injects hosting/agent adapters and optionally a workspace strategy or workflow. `hosting(project)` returns a host-qualified adapter. `agents` maps provider names to adapters. The default workspace uses the existing checkout. One DBOS runtime runs per Node process; one runner owns each configuration and checkout.
+
+`pathBaseDirectory` must identify an existing directory. It resolves relative
+state, checkout, and prompt-file paths once when the runner is constructed.
+Omitting it preserves current-working-directory behavior for SDK callers.
+`promptBaseDirectory` retains its narrower role and, when both are supplied,
+overrides only relative prompt files.
 
 `start()` validates registration, acquires ownership, launches DBOS, registers concurrency-one project queues, and starts polling. `poll(projectId?)` performs an immediate scan. `pause(projectId)` stops new starts while active work continues. `resume(projectId)` refuses blocked checkouts. `stop(runId)` waits for the active invocation/process to end, or cancels queued work. `retry(runId)` requires a terminal failed/blocked/cancelled run and a clean checkout, then returns a new linked run ID. `recover(runId)` returns a new execution ID for publication recovery of the same run. `shutdown()` stops intake, cancels and awaits active work, closes DBOS and releases ownership.
 
@@ -29,7 +35,7 @@ commit together; failure preserves the blocked state.
 | `prepare()`                              | Require clean Git state; fetch base and create unique branch                 |
 | `implement()`                            | Fresh implementation session; reject unexpected commits or branch changes    |
 | `validate()`                             | Run commands and verify unchanged diff; false means no change                |
-| `writePublication()`                     | Fresh writer session; schema-check and persist generated text                |
+| `writePublication()`                     | Validate text; finalize persisted run/co-author trailers from retained changes |
 | `commit()` / `push()`                    | Separate reconciled Git effects using the verified change set                |
 | `publish()`                              | Find existing request by branch before creating a draft                      |
 | `review()`                               | Fresh read-only reviewer; exact published diff, head and validation evidence |
@@ -44,7 +50,7 @@ checks. Stage overrides replace only `defaultPrompt`. Custom stages have no
 inferred built-in default; resolve file-based custom stages before invocation
 with `resolveStagePrompt(stage, defaultPrompt, baseDirectory)` if they must be
 frozen alongside startup configuration. The runner resolves built-in prompt files
-at construction using `promptBaseDirectory`.
+at construction using `promptBaseDirectory ?? pathBaseDirectory ?? process.cwd()`.
 
 ```ts
 await operations.invoke("report", stage, {
@@ -135,7 +141,7 @@ Caveats:
 
 ## Extension contracts
 
-`Workspace` separates `check`, `prepare`, `inspect`, `verify`, `commit`, `push` and `release`. `Snapshot` contains branch/head, changed paths, diff and a content fingerprint. Never implement release by discarding files. A future isolated workspace implementation can replace this interface without changing workflow composition.
+`Workspace` separates `check`, `prepare`, `inspect`, `verify`, `commit`, `push` and `release`. `Snapshot` contains branch/head, changed paths, diff and a content fingerprint. `commit` receives the already-finalized message, including attribution and run marker, and must preserve native Git identity selection. Never implement release by discarding files. A future isolated workspace implementation can replace this interface without changing workflow composition.
 
 `prepare`, `commit` and `push` receive an optional final `AbortSignal`. Custom workspaces must stop their subprocesses before settling a cancelled operation. The existing-checkout strategy journals Git processes under the Git directory; ownership acquisition rejects surviving process groups after a runner crash.
 
@@ -154,6 +160,11 @@ only. This callback must not mutate Store records. Operator tools should use
 
 Invocation records include project/run IDs, stable DBOS step ID and name, invocation ID, attempt, timestamps, requested/effective profile, provider, effective task prompt/source/hash, output-contract and evidence identities, artifact path and session state (`pending`, `available`, `unavailable`). Repeated custom steps retain separate invocations. A retry has a separate run record linked to its predecessor.
 
+Writable invocation before/after evidence is retained on the run. Publication
+finalization persists contributing provider identities in first-contribution
+order, independent of custom stage names. Recovery reuses that provenance and
+the finalized publication message.
+
 `request(kind,target)` queues the same `pause`, `resume`, `stop`, `retry`, or `recover` commands used by the CLI/TUI; `commands()` reports pending/success/failure. A runner must be active to execute them. `finishCommand` and record-writing methods support adapters and custom workflows; operator tools should prefer commands over direct mutation.
 
 ## Publication recovery

package/docs/configuration.md

@@ -1,29 +1,46 @@
 # Configuration
 
-The CLI reads `agent-workflows.json`, or `--config PATH`. Unknown properties are rejected by Zod. Paths are local filesystem paths; checkout paths are canonicalized before ownership is acquired. Use absolute paths when launching from different working directories.
+The CLI reads `agent-workflows.json`, or `--config PATH`. Both paths resolve from
+the launch directory. Unknown properties are rejected by Zod. Relative
+configuration-owned paths resolve from the directory containing the resolved
+configuration file, independently of where the CLI is launched. Use
+`--config-base-directory DIRECTORY` to select another base; a relative option
+value resolves from the launch directory. The base must be an existing directory
+and is canonicalized before startup.
 
 | Runner field     | Default / meaning                                                                                         |
 | ---------------- | --------------------------------------------------------------------------------------------------------- |
 | `id`             | Required stable letters/digits/underscore/hyphen identity; scopes records and queues                      |
 | `databaseUrlEnv` | `AGENT_WORKFLOWS_DATABASE_URL`; environment variable containing a PostgreSQL connection URL with username |
-| `stateDirectory` | `.agent-workflows`; must resolve outside every managed checkout                                                   |
+| `stateDirectory` | `.agent-workflows`; relative to the configuration base and outside every managed checkout                    |
 | `projects`       | Nonempty array; duplicate IDs or canonical checkout roots are rejected                                    |
 
 | Project field          | Default / meaning                                                                                   |
 | ---------------------- | --------------------------------------------------------------------------------------------------- |
-| `id`, `checkout`       | Required stable identity and existing Git repository root                                           |
+| `id`, `checkout`       | Required stable identity and existing Git repository root; relative to the configuration base       |
 | `hosting`              | `provider` (`github`/`gitlab`), web `origin`, `repository`, and `tokenEnv`; no serialized tokens    |
 | `labels`               | `['ready-for-agent']`; all labels must match                                                        |
 | `baseBranch`, `remote` | `main`, `origin`; Git remote is independent of hosting API origin                                   |
 | `branchTemplate`       | `agent/{issue}-{attempt}`; `{issue}` required; `{attempt}` and `{run}` supported                    |
 | `pollIntervalMs`       | 30000; minimum 100                                                                                  |
-| `gitIdentity`          | Required `name` and `email`; used by application commits                                            |
+| `includeAgentCoAuthors` | `true`; append co-author trailers for providers whose writable invocations produced retained changes |
 | `validation`           | Array of `{command,args,timeoutMs}`; no shell expansion; timeout defaults to 300000 ms              |
 | `agent`                | Required default profile                                                                            |
 | `stages`               | `implementation`, `publication`, `review`; each has optional `profile`, `prompt`, `promptFile`, `timeoutMs` |
 
 Issues are selected in ascending issue-number order within each intake scan. Deduplication persists across restarts. An explicit retry is a new numbered attempt linked through `retryOf`.
 
+Absolute configuration paths remain absolute. Effective state and checkout
+paths are normalized once during startup before safety and ownership checks, so
+a later working-directory change cannot redirect a running process. Validation
+commands still execute in the canonical checkout; command names and arguments
+are passed unchanged and are not rebased to the configuration directory.
+
+`init` writes relative checkout and external sibling-state paths from the
+effective configuration base. It still refuses to overwrite an existing file.
+When the configuration is in the checkout root, the checkout is `.` and state
+is the relative sibling `<checkout-name>.agent-workflows`.
+
 ## CLI environment files
 
 Select one file explicitly for any CLI command:
@@ -128,11 +145,12 @@ in inspection explicitly; do not present an incomplete review as a clean review.
 These exact defaults are checked against the runtime source.
 
 Use either nonblank literal `prompt` text or a `promptFile` path, never both.
-Files must contain nonblank UTF-8 text. Relative paths resolve from the CLI
-configuration file's directory, independently of the launch directory; absolute
-paths are allowed. Files load once when the runner is constructed. Restart to
-apply edits. No templating, interpolation, or includes are supported. SDK callers
-supply `promptBaseDirectory` for relative paths.
+Files must contain nonblank UTF-8 text. Relative paths use the same configuration
+base as state and checkout paths; absolute paths are allowed. Files load once
+when the runner is constructed. Restart to apply edits. No templating,
+interpolation, or includes are supported. SDK callers use `pathBaseDirectory` as
+the general base. `promptBaseDirectory`, when supplied, overrides it for prompt
+files only.
 
 ```json
 "stages": {
@@ -146,6 +164,29 @@ supply `promptBaseDirectory` for relative paths.
 without aliases. Configure skills in the selected agent runtime and request them
 in task text. Old invocation records and skill snapshots remain readable.
 
+## Git identity and agent attribution
+
+Commits use Git's native author and committer selection. The application does
+not configure, validate, snapshot, or override identity. Repository, worktree,
+global, system, and identity environment settings therefore behave as they do
+for `git commit`, including distinct author and committer identities. Missing or
+invalid identity fails at the commit operation with Git's error. The removed
+`gitIdentity` property is rejected as unknown input.
+
+Agent assistance is represented separately. With `includeAgentCoAuthors: true`,
+the finalized commit message includes each provider once, ordered by its first
+successful writable invocation that produced a retained change:
+
+- `Codex <noreply@openai.com>` (OpenAI's published implementation convention)
+- `Copilot <223556219+Copilot@users.noreply.github.com>` (GitHub's current
+  first-party convention, not a stable product API guarantee)
+
+Read-only publication/review invocations and writable invocations with no
+accepted retained change are not attributed. Existing trailers are preserved,
+matching agent trailers are deduplicated, and exactly one
+`Agent-Workflows-Run` trailer remains. Set `includeAgentCoAuthors: false` per
+project to disable injection; existing publication trailers are not removed.
+
 Stage timeout defaults to 30 minutes, including profile validation and at most
 one format-correction attempt. Correction uses a fresh inspection-only session
 and only the remaining deadline. Provider failures, cancellation, timeout and