@opengsd/gsd-core 1.13.0 → 1.14.0

package/gsd-core/bin/lib/state.cjs

@@ -61,6 +61,13 @@ const planDependencyGraphMod = require("./plan-dependency-graph.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete } = verificationMod;
+// #4129: the single owner of "count the ROADMAP's milestone Complete rows"
+// (phase-lifecycle.cts) — reused for the completed-phases numerator floor so
+// this scan cannot grow a second ROADMAP parser. Pure computation module (no
+// I/O), so it introduces no cycle on this path.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLifecycleMod = require("./phase-lifecycle.cjs");
+const { deriveProgressFromRoadmap } = phaseLifecycleMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -286,7 +293,7 @@ function cmdStateGet(cwd, section, raw) {
         // Try to find markdown section or field
         const fieldEscaped = (0, pattern_cjs_1.escapeRegex)(section);
         // Check for **field:** value (bold format)
-        const boldPattern = new RegExp(`\\*\\*${fieldEscaped}:\\*\\*\\s*(.*)`, 'i');
+        const boldPattern = new RegExp(`^[ \\t]*\\*\\*${fieldEscaped}:\\*\\*[ \\t]*(.*)`, 'im');
         const boldMatch = content.match(boldPattern);
         if (boldMatch) {
             output({ [section]: boldMatch[1].trim() }, raw, boldMatch[1].trim());
@@ -314,13 +321,10 @@ function readTextArgOrFile(cwd, value, filePath, label) {
         return value;
     // Path traversal guard: ensure file resolves within project directory
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
-    const { validatePath } = require('./security.cjs');
-    const pathCheck = validatePath(filePath, cwd, { allowAbsolute: true });
-    if (!pathCheck.safe) {
-        throw new Error(`${label} path rejected: ${pathCheck.error}`);
-    }
+    const { assertWithinRoot, PathAcceptance } = require('./security.cjs');
+    const contained = assertWithinRoot(filePath, cwd, `${label} path`, PathAcceptance.AbsoluteInsideRoot);
     try {
-        return node_fs_1.default.readFileSync(pathCheck.resolved, 'utf-8').trimEnd();
+        return node_fs_1.default.readFileSync(contained, 'utf-8').trimEnd();
     }
     catch {
         throw new Error(`${label} file not found: ${filePath}`);
@@ -489,7 +493,31 @@ function cmdStateUpdate(cwd, field, value) {
         // (#3345's direction) — reported separately from `updated` because this
         // command's contract is a single-field boolean, not a per-field array.
         const reconciled = reconcileReportedFields(statePath, preWriteState, updated ? [field] : [], divergedFields);
-        updated = reconciled.includes(field);
+        // #4488: `updateCore` itself already told us whether it matched the field
+        // (`updated`, captured above `readModifyWriteStateMd` runs it) — that is a
+        // real signal, not a guess. `reconcileReportedFields` answers a DIFFERENT
+        // question ("what changed on disk") and, per its own docstring, reports
+        // `[]` whenever `preWriteState.fm` is `undefined`. That happens in two
+        // known cases, both of which mean "no snapshot was ever captured", not
+        // "nothing happened": (a) `readModifyWriteStateMd`'s #948 no-op guard
+        // fires because the transform's output was byte-identical to the input —
+        // the requested value already equals what's on disk, so the field WAS
+        // found and there was simply nothing left to change; (b)
+        // `applyPostSyncPreservation`'s `isUnparseableFrontmatter` early return —
+        // the ORIGINAL frontmatter block was malformed, so preservation never
+        // runs, yet `readModifyWriteStateMd` still persists the transform's raw
+        // output via `platformWriteSync`. In neither case did preservation
+        // discard or rewrite what the transform wrote, so trusting the
+        // transform's own `updated` signal here is never a false positive.
+        // Collapsing either case into the same `false` as "field not found" is
+        // the #4488 bug — `explainUpdateFailure` then reports a message that is
+        // actively false (it tells the caller to add a line that is already
+        // there). Every other `false` origin (case-D fallback did not apply, or
+        // the transform genuinely found nothing) is unaffected: there
+        // `preWriteState.fm` is defined (a normal sync ran) or `updated` was
+        // already false before this line.
+        const noopBecauseAlreadyCorrect = updated && preWriteState.fm === undefined;
+        updated = reconciled.includes(field) || noopBecauseAlreadyCorrect;
         const preserved = reconciled.filter((f) => f !== field);
         if (updated) {
             // #3699 case D: surfaced so a caller can tell "wrote the body source" from
@@ -1560,6 +1588,18 @@ function cmdStateResolveBlocker(cwd, text, raw) {
     }
 }
 function cmdStateRecordSession(cwd, options, raw) {
+    // #4186: a bare invocation is a usage error, not a heartbeat write. The
+    // pre-#4186 handler accepted zero arguments and still refreshed
+    // `Last session` / `Last Date` / `last_updated` — a caller probing the
+    // command's signature (the way other subcommands encourage) silently
+    // mutated STATE.md. Mirrors `state update`'s required-arg guard
+    // (cmdStateUpdate: `error('field and value required for state update')`),
+    // including its ordering: validation precedes the STATE.md existence
+    // check. Either flag suffices — `--resume-file` alone carries an explicit
+    // value the handler must persist.
+    if (!options.stopped_at && (options.resume_file === undefined || options.resume_file === null)) {
+        error('stopped-at or resume-file required for state record-session');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -2512,7 +2552,10 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // own comment on that field). Folding this consumer onto the raw
                         // summaries-met flag was the exact "consolidate two of three and
                         // leave the third" gap §7.4's forcing function rules out.
-                        if (isPhaseComplete(phaseDir).value.complete)
+                        // #612: `phaseConvention` threaded so a bracket phase dir resolves
+                        // and scopes its verification report like its legacy twin — the
+                        // read-side half of the same thread cmdStateSync gets below.
+                        if (isPhaseComplete(phaseDir, { convention: phaseConvention }).value.complete)
                             diskCompletedPhases++;
                     }
                     // Count phase headings from ROADMAP — single source of truth for
@@ -2619,6 +2662,34 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // write silently clobbered the three stored siblings with the
                         // under-scoped disk numbers.
                         const diskCountsWithheld = milestonedButUnbounded || roadmapAbsentWithAssertedMilestone;
+                        // #4129: floor the completed-phases numerator at the ROADMAP's own
+                        // milestone Complete-row count. The disk numerator counts ONLY
+                        // phase dirs whose *-VERIFICATION.md routes `passed` (isPhaseComplete,
+                        // #2957 disk-strict — the gate stays untouched), so a completed
+                        // phase whose verification reads `stale` (a SUMMARY committed or
+                        // edited after it, #2348 clean-commit-time clock) or `missing`
+                        // (pre-verification era, hand-flipped ROADMAP row) drops out of the
+                        // count forever — while every other surface (the ROADMAP row
+                        // `phase complete` just flipped, the body `Completed Phases` field
+                        // completePhaseCore derives from deriveProgressFromRoadmap) still
+                        // asserts the phase complete. max(disk, ROADMAP) keeps the disk
+                        // signal for gap detection (a verification-passed phase whose ROADMAP
+                        // row is not yet flipped still counts) while never UNDER-counting
+                        // what the ROADMAP asserts. Scoped exactly like the denominator:
+                        // the same milestone window (roadmapScope), the same
+                        // safeToUseRoadmapCount gate, and never under the #3354/#3573
+                        // withhold — a whole-document Complete-row count must not leak
+                        // through an untrustworthy scope. Reuses deriveProgressFromRoadmap
+                        // (phase-lifecycle.cts, the one owner of "read the Progress table")
+                        // — no second ROADMAP parser here. A ROADMAP without a canonical
+                        // `## Progress` table resolves no table → floor inert (disk count
+                        // stands), the owner's own answer to "what is countable".
+                        const roadmapCompletedPhases = roadmapScope !== null && safeToUseRoadmapCount && !diskCountsWithheld
+                            ? deriveProgressFromRoadmap(roadmapScope).completedPhases
+                            : null;
+                        const flooredCompletedPhases = roadmapCompletedPhases !== null
+                            ? Math.max(diskCompletedPhases, roadmapCompletedPhases)
+                            : diskCompletedPhases;
                         return {
                             // The two WITHHOLD shapes (#3354 milestoned-but-unbounded, #3573
                             // roadmap-absent-with-asserted-milestone) must be evaluated BEFORE
@@ -2629,7 +2700,7 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                                 ? null
                                 : (safeToUseRoadmapCount ? Math.max(phaseDirs.length, roadmapPhaseCount) : phaseDirs.length),
                             milestoneBounded,
-                            completedPhases: diskCountsWithheld ? null : diskCompletedPhases,
+                            completedPhases: diskCountsWithheld ? null : flooredCompletedPhases,
                             totalPlans: diskCountsWithheld ? null : diskTotalPlans,
                             completedPlans: diskCountsWithheld ? null : diskTotalSummaries,
                             phaseDirScope,
@@ -2722,19 +2793,19 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
             progressPercent = parseInt(pctMatch[1], 10);
     }
     let normalizedStatus = (0, state_document_cjs_1.normalizeStateStatus)(status, pausedAt);
-    // #3578: normalizeStateStatus matches 'complete' as a case-insensitive
-    // SUBSTRING, so the phase-completion prose cmdStateCompletePhase writes to
-    // the body (`Phase ${N} complete`) collapses to the milestone-level
-    // 'completed' status even when other phases remain open. Phase-level
-    // prose must never decide milestone-level status — completedPhases /
-    // totalPhases / diskScope, already derived above from a disk scan, are
-    // the authority on whether the MILESTONE is actually done. Only override
-    // when: (a) normalizeStateStatus actually landed on 'completed'; (b) the
-    // raw prose is UNAMBIGUOUSLY phase-completion prose — the anchored
-    // pattern below deliberately excludes "All phases complete" (no `\S+`
-    // phase token) and milestone-close prose like "v1.0 milestone complete"
-    // (no leading "phase"); and (c) the counters are trustworthy (a COMPLETE
-    // disk scope, both counts are finite numbers, and a positive
+    // #3578: the declared status vocabulary (#4186) recognizes
+    // `Phase ${N} complete` (state.cts's own phase-completion write) and maps
+    // it to `completed`, so the phase-completion prose still collapses to the
+    // milestone-level status even when other phases remain open — this guard
+    // demotes it back. Phase-level prose must never decide milestone-level
+    // status — completedPhases / totalPhases / diskScope, already derived above
+    // from a disk scan, are the authority on whether the MILESTONE is actually
+    // done. Only override when: (a) normalizeStateStatus actually landed on
+    // 'completed'; (b) the raw prose is UNAMBIGUOUSLY phase-completion prose —
+    // the anchored pattern below deliberately excludes "All phases complete"
+    // (no `\S+` phase token) and milestone-close prose like "v1.0 milestone
+    // complete" (no leading "phase"); and (c) the counters are trustworthy (a
+    // COMPLETE disk scope, both counts are finite numbers, and a positive
     // denominator) and affirmatively disagree with 'completed'. In every
     // other case normalizedStatus is left exactly as normalizeStateStatus
     // returned it.
@@ -2996,6 +3067,75 @@ function readStoredTotalPlans(existingFm) {
 function readStoredCompletedPlans(existingFm) {
     return readStoredProgressCounter(existingFm, 'completed_plans');
 }
+/**
+ * #4129: is this authoritativeFm value a PARTIAL progress intent? The #2736
+ * seam was string-only (names); #4129 extends it with one object direction —
+ * the `progress` key carrying the sub-keys a transition resolved
+ * authoritatively (completePhase's ROADMAP-derived completed_phases/percent).
+ * Anything else keeps the seam's existing contract untouched.
+ */
+function isPartialProgressIntent(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * #4129: merge a PARTIAL progress intent (see isPartialProgressIntent) into a
+ * frontmatter object's `progress` block. Sub-keys are accepted only when they
+ * are a declared `progress.*` row in FIELD_CLASSIFICATION — the single policy
+ * source (ADR-3408 §8.5) decides which leaves exist; an intent may not invent
+ * one. Returns whether anything changed.
+ *
+ * `completedOnlyRaise` (both application sites use it): completed counters
+ * apply only when strictly greater than what is already in the block, so no
+ * intent can LOWER a count another trustworthy signal already established —
+ * at the pre-preservation site the disk derivation's own count (a
+ * verification-passed phase whose ROADMAP row drifted behind), at the
+ * post-preservation re-assert the #2969 monotonic property preservation just
+ * enforced. `percent` follows its sibling: it is applied when a completed
+ * counter moved this call (the intent percent was computed from the intent
+ * counters and is coherent with them) or when the block has no percent to
+ * lose (a repair, never a regression of an upstream withhold — the withhold
+ * nulled percent upstream precisely so no write would re-assert one over
+ * untrustworthy counts; here the intent's own counts ARE the trustworthy
+ * source, the post-completion ROADMAP).
+ */
+function applyAuthoritativeProgressSubkeys(fm, intent, opts) {
+    const current = fm['progress'];
+    const base = isPartialProgressIntent(current)
+        ? { ...current }
+        : {};
+    let changed = false;
+    let completedMoved = false;
+    for (const [subkey, value] of Object.entries(intent)) {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            continue;
+        if (!getFieldClassification(`progress.${subkey}`))
+            continue;
+        const isCompletedCounter = subkey === 'completed_phases' || subkey === 'completed_plans';
+        if (isCompletedCounter && opts.completedOnlyRaise) {
+            const currentNum = (0, state_document_cjs_1.toFiniteNumber)(base[subkey]);
+            if (currentNum !== null && currentNum >= value)
+                continue;
+        }
+        if (isCompletedCounter && !Object.is(base[subkey], value))
+            completedMoved = true;
+        if (!Object.is(base[subkey], value)) {
+            base[subkey] = value;
+            changed = true;
+        }
+    }
+    // percent: applied only when a completed counter moved (coherent with the
+    // counters that just landed) or when no percent exists to contradict.
+    const intentPercent = intent['percent'];
+    if (typeof intentPercent === 'number' && Number.isFinite(intentPercent) && (completedMoved || (0, state_document_cjs_1.toFiniteNumber)(base['percent']) === null)) {
+        if (!Object.is(base['percent'], intentPercent)) {
+            base['percent'] = intentPercent;
+            changed = true;
+        }
+    }
+    if (changed)
+        fm['progress'] = base;
+    return changed;
+}
 function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanentEmptyFallback) {
     // Read existing frontmatter BEFORE stripping — it may contain values
     // that the body no longer has (e.g., Status field removed by an agent).
@@ -3201,11 +3341,22 @@ function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanent
     // parenthetical (`Closer-ruling measurement (D1a)` → `D1a`) — never runs
     // the final word on a field the transition just resolved. The prose parser
     // remains the fallback for genuinely unknown prose only.
+    // #4129: the `progress` key carries a PARTIAL block (the object direction of
+    // this seam — see applyAuthoritativeProgressSubkeys) for the same reason:
+    // completePhase holds the POST-completion ROADMAP, and the disk scan this
+    // function drives reads the PRE-completion one. The intent is applied as a
+    // FLOOR here too (completedOnlyRaise): a derivation that already counted
+    // MORE completed phases than the ROADMAP table asserts (verification-passed
+    // phases whose table rows drifted behind) must not be lowered by the intent
+    // — the two signals agree on direction (up), never on subtraction.
     if (authoritativeFm) {
         for (const [key, value] of Object.entries(authoritativeFm)) {
             if (typeof value === 'string' && value.trim().length > 0) {
                 derivedFm[key] = value;
             }
+            else if (key === 'progress' && isPartialProgressIntent(value)) {
+                applyAuthoritativeProgressSubkeys(derivedFm, value, { completedOnlyRaise: true });
+            }
         }
     }
     // #3257: propagate full-line frontmatter comments from the extracted source onto the
@@ -3782,6 +3933,10 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
     // (equal), so the #1695 restore fires and would put the stale pre-transition
     // name back over the authoritative one. Intent beats both the prose
     // re-derivation and the curated restore — the transition just resolved it.
+    // #4129: for the `progress` key the re-assert is a FLOOR, not an override —
+    // the #2969 monotonic property preservation just enforced (completed
+    // counters never move down) must not be undone by the intent, so completed
+    // sub-keys apply only-raise here (see applyAuthoritativeProgressSubkeys).
     let authoritativeReasserted = false;
     if (authoritativeFm) {
         for (const [key, value] of Object.entries(authoritativeFm)) {
@@ -3789,6 +3944,11 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
                 preservation.postFm[key] = value;
                 authoritativeReasserted = true;
             }
+            else if (key === 'progress' && isPartialProgressIntent(value)) {
+                if (applyAuthoritativeProgressSubkeys(preservation.postFm, value, { completedOnlyRaise: true })) {
+                    authoritativeReasserted = true;
+                }
+            }
         }
     }
     let finalContent = syncedContent;
@@ -4454,6 +4614,26 @@ function cmdStateJson(cwd, raw) {
  * Fixes: #1102 (plan counts), #1103 (status/last_activity), #1104 (body text).
  */
 function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
+    // #4138: `--phase` is this verb's one required argument, and an invocation
+    // that names no phase must fail closed BEFORE any read-modify-write runs —
+    // previously the missing flag flowed through as null and the transition
+    // serialised `String(null)` into the body (`Phase: null — EXECUTING`,
+    // `Status: Executing Phase null`, `last_activity_desc: Phase null execution
+    // started`) while the post-sync frontmatter rebuild dropped current_phase /
+    // current_phase_name entirely, so a single argument-less call un-set the
+    // phase identity. The guard mirrors the sibling usage errors that already
+    // exit non-zero (`state update`'s "field and value required", the router's
+    // "unexpected positional argument" / "Invalid --plans value"), NOT
+    // `cmdStateMilestoneSwitch`'s `output({error})` form, which exits 0 — the
+    // issue's Expected is explicit: "Exit non-zero with a usage message and
+    // write nothing." Empty and whitespace-only values are the same missing
+    // argument (CONTRIBUTING.md CLI matrix); a flag-shaped `--phase --name x`
+    // resolves to null in parseNamedArgs and lands here too. Runs before the
+    // STATE.md existence check so argument validation always precedes I/O, and
+    // before claimMilestonePhase so no phase-"null" milestone claim is taken.
+    if (phaseNumber == null || String(phaseNumber).trim() === '') {
+        error('phase required (--phase <N>)');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -4467,7 +4647,11 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     // #1230 post-sync preservation, and the no-op write guard.
     const intent = {
         kind: 'beginPhase',
-        phaseNumber,
+        // The guard above made this non-null/non-empty; `error` is never-returning
+        // at runtime but this module's destructured io binding does not narrow CFA,
+        // so the narrowed fact is restated once (cmdStateUpdate's `field as string`
+        // idiom, state.cts:782).
+        phaseNumber: phaseNumber,
         phaseName: phaseName ?? null,
         planCount: planCount ?? null,
     };
@@ -4763,6 +4947,12 @@ function updatePerformanceMetricsSection(content, cwd, phaseNum, planCount, summ
  * Updates Status to "Ready to execute", Total Plans, Last Activity.
  */
 function cmdStatePlannedPhase(cwd, phaseNumber, phaseName, planCount, raw) {
+    // #4383: mirror begin-phase's command-boundary guard. A missing phase must
+    // fail before even looking up STATE.md so no invalid invocation can enter
+    // the read-modify-write path and serialize a null/blank phase identity.
+    if (phaseNumber == null || String(phaseNumber).trim() === '') {
+        error('phase required (--phase <N>)');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -4778,7 +4968,7 @@ function cmdStatePlannedPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     // still owns the lock, the #1230 preservation, and the no-op write guard.
     const intent = {
         kind: 'plannedPhase',
-        phaseNumber,
+        phaseNumber: phaseNumber,
         phaseName: phaseName ?? null,
         planCount: planCount ?? null,
     };
@@ -5134,7 +5324,10 @@ function cmdStateValidate(cwd, raw, opts = {}) {
         // ("verification passed" drift), not a false S007.
         const files = node_fs_1.default.readdirSync(phaseDirPath);
         const phaseDirBaseName = node_path_1.default.basename(phaseDirPath);
-        const verificationFiles = scopeToPhase(files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md')), phaseDirBaseName);
+        // #612: `validateConvention` threaded (already resolved above for
+        // `phaseKeyFromDir`) so the S006/S007 scan scopes bracket dirs by
+        // their real token instead of the include-everything fail-safe.
+        const verificationFiles = scopeToPhase(files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md')), phaseDirBaseName, validateConvention);
         for (const vf of verificationFiles) {
             try {
                 const vContent = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDirPath, vf), 'utf-8');
@@ -5325,7 +5518,10 @@ function cmdStateSync(cwd, options, raw) {
         // was a second, independent consumer of the same raw field the initial
         // migration missed — without it, `state sync` and `state json` disagreed
         // on completed_phases for the identical disk state.
-        if (isPhaseComplete(dirPath).value.complete)
+        // #612: `syncConvention` threaded — the write-side half of
+        // buildStateFrontmatter's thread above, so `state sync` and `state json`
+        // keep agreeing on completed_phases under the bracket convention.
+        if (isPhaseComplete(dirPath, { convention: syncConvention }).value.complete)
             diskCompletedPhases++;
         // Track the highest phase with incomplete plans (or any plans)
         const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));

package/gsd-core/bin/lib/surface.cjs

@@ -364,14 +364,25 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     try {
         for (const kind of layout.kinds) {
             let staged;
-            if (kind.kind === 'agents') {
+            // #4211: kimi-agents is an AGENT kind — kimiAgentsKind.stage() forwards
+            // agentCtx into stageAgentsForRuntimeWithConverter exactly as agentsKind
+            // does, and createRuntimeArtifactInstallPlan hands every kind the
+            // context. Staging it bare here dropped the path-prefix rewrites and the
+            // attribution trailer from Kimi's generated subagents, and (under an
+            // unmodified `full` profile) staged only the skill-referenced subset the
+            // install path stages with `skills: '*'`.
+            if (kind.kind === 'agents' || kind.kind === 'kimi-agents') {
                 const agentProfile = _isUnmodifiedFull ? { ...resolved, skills: '*' } : resolved;
                 staged = kind.stage(agentProfile, agentCtx);
             }
             else {
                 staged = kind.stage(resolved);
             }
-            if (kind.kind === 'skills') {
+            // #4211: kimi-agents takes the skill-body rewrite too —
+            // createRuntimeArtifactInstallPlan routes `skills` and `kimi-agents`
+            // through rewriteStagedSkillBodies together, so omitting it here left
+            // Kimi's surface-materialized prompts with unrewritten paths.
+            if (kind.kind === 'skills' || kind.kind === 'kimi-agents') {
                 runtimeArtifactConversion.rewriteStagedSkillBodies(staged, {
                     runtime: layout.runtime,
                     configDir: layout.configDir,
@@ -572,6 +583,53 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest, runtime) {
     // (no agentFileExtension declared) keep the staged filename verbatim.
     const _agentExt = runtime ? runtimeArtifactConversion.agentFileExtensionFor(runtime) : undefined;
     const isRenamedAgents = !!_agentExt && kindName === 'agents';
+    if (kindName === 'kimi-agents') {
+        // #4211: Kimi's managed tree is `gsd.yaml` + `gsd.md` + `subagents/gsd-*.{yaml,md}`
+        // (runtime-artifact-layout.cts kimiAgentsKind), and install copies it
+        // RECURSIVELY (_copyStaged in src/install-engine.cts). Surface apply fell
+        // through to the flat command/agent branch below, which reads only `*.md`
+        // at the top level: the YAML half and the whole subagents/ subtree were
+        // dropped, and `gsd.md` was written as `gsdgsd.md` (the flat branch
+        // re-applies kind.prefix to a name that already carries it). A surface
+        // change could therefore corrupt Kimi's installed artifacts while still
+        // reporting success.
+        node_fs_1.default.cpSync(stagedDir, destDir, { recursive: true });
+        // Prune GSD-owned files the new surface no longer stages, with exactly the
+        // ownership rule install's _removeGsdEntries applies to this kind: the two
+        // root files, and `gsd-`-prefixed .yaml/.md under subagents/. Everything
+        // else in the directory is user-owned and is preserved.
+        const _rootStaged = new Set(node_fs_1.default.readdirSync(stagedDir));
+        for (const fileName of ['gsd.yaml', 'gsd.md']) {
+            if (!_rootStaged.has(fileName)) {
+                try {
+                    node_fs_1.default.rmSync(node_path_1.default.join(destDir, fileName), { force: true });
+                }
+                catch { /* ignore */ }
+            }
+        }
+        const _stagedSubagentsDir = node_path_1.default.join(stagedDir, 'subagents');
+        const _destSubagentsDir = node_path_1.default.join(destDir, 'subagents');
+        const _stagedSubagents = node_fs_1.default.existsSync(_stagedSubagentsDir)
+            ? new Set(node_fs_1.default.readdirSync(_stagedSubagentsDir))
+            : new Set();
+        if (node_fs_1.default.existsSync(_destSubagentsDir)) {
+            for (const entry of node_fs_1.default.readdirSync(_destSubagentsDir, { withFileTypes: true })) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.startsWith('gsd-'))
+                    continue;
+                if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.md'))
+                    continue;
+                if (_stagedSubagents.has(entry.name))
+                    continue;
+                try {
+                    node_fs_1.default.rmSync(node_path_1.default.join(_destSubagentsDir, entry.name), { force: true });
+                }
+                catch { /* ignore */ }
+            }
+        }
+        return;
+    }
     if (kindName === 'skills') {
         // Skills kind: work with directories, not files.
         // Each staged entry is a directory named ${prefix}${stem}.

package/gsd-core/bin/lib/task-command-router.cjs

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error, ERROR_REASON } = ioMod;
@@ -108,12 +109,14 @@ function routeResolveContent({ args, cwd, raw }, deps = {}) {
         return;
     }
     const projectRoot = node_path_1.default.resolve(cwd || process.cwd());
-    const resolvedPlanPath = node_path_1.default.resolve(projectRoot, plan);
-    const rel = node_path_1.default.relative(projectRoot, resolvedPlanPath);
-    if (rel === '..' || rel.startsWith(`..${node_path_1.default.sep}`)) {
+    // Lexical containment (ADR-4650): this path is validated before existence is
+    // checked below, so realpath resolution is neither available nor required.
+    const contained = (0, security_cjs_1.tryWithinRootLexical)(plan, projectRoot);
+    if (contained === null) {
         error(`Plan file is outside project scope: ${plan}`, ERROR_REASON.USAGE);
         return;
     }
+    const resolvedPlanPath = contained;
     if (!node_fs_1.default.existsSync(resolvedPlanPath)) {
         error(`Plan file not found: ${plan}`, ERROR_REASON.USAGE);
         return;
@@ -173,11 +176,14 @@ function routeTaskCommand({ args, cwd, raw }) {
     else if (args[2]) {
         const projectRoot = node_path_1.default.resolve(cwd || process.cwd());
         const requestedPath = args[2];
-        const resolvedTaskPath = node_path_1.default.resolve(projectRoot, requestedPath);
-        const rel = node_path_1.default.relative(projectRoot, resolvedTaskPath);
-        if (rel === '..' || rel.startsWith(`..${node_path_1.default.sep}`)) {
+        // Lexical containment (ADR-4650): validated before existence is checked below.
+        // `error()` here does not return/throw (preserved from before this migration),
+        // so resolvedTaskPath must still be computed identically on the rejected path.
+        const contained = (0, security_cjs_1.tryWithinRootLexical)(requestedPath, projectRoot);
+        if (contained === null) {
             error(`Task file is outside project scope: ${requestedPath}`, ERROR_REASON.USAGE);
         }
+        const resolvedTaskPath = contained ?? node_path_1.default.resolve(projectRoot, requestedPath);
         if (!node_fs_1.default.existsSync(resolvedTaskPath)) {
             error(`Task file not found: ${requestedPath}`, ERROR_REASON.USAGE);
         }

package/gsd-core/bin/lib/uat.cjs

@@ -322,7 +322,7 @@ function cmdRenderCheckpoint(cwd, options = {}, raw) {
     if (!filePath) {
         error('UAT file required: use uat render-checkpoint --file <path>');
     }
-    const resolvedPath = (0, security_cjs_1.requireSafePath)(filePath, cwd, 'UAT file', { allowAbsolute: true });
+    const resolvedPath = (0, security_cjs_1.requireSafePath)(filePath, cwd, 'UAT file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
     if (!node_fs_1.default.existsSync(resolvedPath)) {
         error(`UAT file not found: ${filePath}`);
     }

package/gsd-core/bin/lib/update-context.cjs

@@ -127,6 +127,23 @@ function preferFirst(entries, preferred) {
     const rest = entries.filter(([rt]) => rt !== preferred);
     return [...pref, ...rest];
 }
+// GLOBAL probe: absolute env candidates first (in preferFirst order, first
+// hasInstall hit wins), then $HOME-relative. Single resolver shared by the
+// preferredConfigDir fast path's same-path dedup and the full cascade (#4197),
+// so both compare against the global dir the resolution would actually select —
+// an env-directed candidate, not necessarily the $HOME-relative pathname.
+function resolveGlobalCandidate(fs, env, home, preferred) {
+    for (const [rt, absdir] of preferFirst(envRuntimeDirs({ env, home }), preferred)) {
+        if (hasInstall(fs, absdir))
+            return { runtime: rt, dir: node_path_1.default.resolve(absdir) };
+    }
+    for (const [rt, reldir] of preferFirst(exports.RUNTIME_DIRS, preferred)) {
+        const cand = node_path_1.default.resolve(home, reldir);
+        if (hasInstall(fs, cand))
+            return { runtime: rt, dir: cand };
+    }
+    return { runtime: '', dir: '' };
+}
 /**
  * Pure resolver. Returns { installedVersion, scope, runtime, gsdDir }.
  */
@@ -137,11 +154,17 @@ function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = ''
     // Fast path: a validated preferredConfigDir (custom --config-dir install).
     if (preferredConfigDir && hasInstall(fs, preferredConfigDir)) {
         const resolvedPref = node_path_1.default.resolve(preferredConfigDir);
+        // Same-path dedup the cascade applies (#4197): a preferred dir that IS the
+        // selected global install (an env candidate or the $HOME-relative dir) is
+        // GLOBAL even when cwd === $HOME also makes it the cwd-relative match.
+        const { dir: globalDir } = resolveGlobalCandidate(fs, env, home, preferred);
         let scope = 'GLOBAL';
-        for (const [, reldir] of exports.RUNTIME_DIRS) {
-            if (node_path_1.default.resolve(cwd, reldir) === resolvedPref) {
-                scope = 'LOCAL';
-                break;
+        if (resolvedPref !== globalDir) {
+            for (const [, reldir] of exports.RUNTIME_DIRS) {
+                if (node_path_1.default.resolve(cwd, reldir) === resolvedPref) {
+                    scope = 'LOCAL';
+                    break;
+                }
             }
         }
         return {
@@ -151,7 +174,6 @@ function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = ''
             gsdDir: preferredConfigDir,
         };
     }
-    const orderedEnv = preferFirst(envRuntimeDirs({ env, home }), preferred);
     const orderedRuntime = preferFirst(exports.RUNTIME_DIRS, preferred);
     // LOCAL probe (relative to cwd).
     let localRuntime = '', localDir = '';
@@ -163,25 +185,9 @@ function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = ''
             break;
         }
     }
-    // GLOBAL probe: absolute env candidates first, then $HOME-relative.
-    let globalRuntime = '', globalDir = '';
-    for (const [rt, absdir] of orderedEnv) {
-        if (hasInstall(fs, absdir)) {
-            globalRuntime = rt;
-            globalDir = node_path_1.default.resolve(absdir);
-            break;
-        }
-    }
-    if (!globalRuntime) {
-        for (const [rt, reldir] of orderedRuntime) {
-            const cand = node_path_1.default.resolve(home, reldir);
-            if (hasInstall(fs, cand)) {
-                globalRuntime = rt;
-                globalDir = cand;
-                break;
-            }
-        }
-    }
+    // GLOBAL probe: absolute env candidates first, then $HOME-relative — the
+    // same resolver the fast path dedups against.
+    const { runtime: globalRuntime, dir: globalDir } = resolveGlobalCandidate(fs, env, home, preferred);
     const localValid = trustedVersionAt(fs, localDir);
     const isLocal = !!localValid && (!globalDir || localDir !== globalDir);
     if (isLocal) {

package/gsd-core/bin/lib/vendor/js-yaml.cjs

@@ -1262,16 +1262,21 @@
                 state.result += _result;
             }
         }
+        function chargeMergeWork(state) {
+            state.totalMergeKeys++;
+            if (state.maxTotalMergeKeys !== -1 && state.totalMergeKeys > state.maxTotalMergeKeys) {
+                throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
+            }
+        }
         function mergeMappings(state, destination, source, overridableKeys) {
             if (!common2.isObject(source)) {
                 throwError(state, "cannot merge mappings; the provided source object is unacceptable");
             }
+            chargeMergeWork(state);
             var sourceKeys = Object.keys(source);
             for (var index = 0, quantity = sourceKeys.length; index < quantity; index += 1) {
                 var key = sourceKeys[index];
-                if (state.maxTotalMergeKeys !== -1 && ++state.totalMergeKeys > state.maxTotalMergeKeys) {
-                    throwError(state, "merge keys exceeded maxTotalMergeKeys (" + state.maxTotalMergeKeys + ")");
-                }
+                chargeMergeWork(state);
                 if (!_hasOwnProperty.call(destination, key)) {
                     setProperty(destination, key, source[key]);
                     overridableKeys[key] = true;
@@ -1299,6 +1304,9 @@
             }
             if (keyTag === "tag:yaml.org,2002:merge") {
                 if (Array.isArray(valueNode)) {
+                    if (valueNode.length > 100) {
+                        throwError(state, "abnormal merge sequence size");
+                    }
                     for (var _index = 0, _quantity = valueNode.length; _index < _quantity; _index += 1) {
                         mergeMappings(state, _result, valueNode[_index], overridableKeys);
                     }