hammoc 1.5.0 → 1.7.0

package/packages/server/dist/utils/harnessBundleSchema.d.ts

@@ -18,6 +18,16 @@ import { z } from 'zod';
  * future-version bundles fall through to the AC5.a "futureBundle" branch
  * before this schema is even consulted (the import service inspects the raw
  * JSON's version field first, then runs full Zod validation).
+ *
+ * `includes` is intentionally LOOSE (`z.array(z.string())`) rather than
+ * `z.array(sectionSchema)` so a `bundleVersion === 1` manifest carrying a
+ * future-domain stranger section (e.g. `['claude-md', 'future-section']`)
+ * still parses. The import service's `computePreview` then surfaces unknown
+ * sections via `preview.unknownSections` per AC5.b instead of bailing with
+ * `compatibility: 'malformed'`. Export-request validation
+ * (`exportBundleRequestSchema`) keeps `sectionSchema` strict — we never
+ * accept unknown sections from outbound callers, only tolerate them
+ * inbound.
  */
 export declare const bundleManifestSchema: z.ZodObject<{
     bundleVersion: z.ZodLiteral<1>;
@@ -25,15 +35,7 @@ export declare const bundleManifestSchema: z.ZodObject<{
     claudeCodeSpecVersion: z.ZodUnion<readonly [z.ZodString, z.ZodNull]>;
     createdAt: z.ZodString;
     sourceProjectSlug: z.ZodString;
-    includes: z.ZodArray<z.ZodEnum<{
-        agents: "agents";
-        hooks: "hooks";
-        commands: "commands";
-        skills: "skills";
-        mcp: "mcp";
-        "claude-md": "claude-md";
-        bmad: "bmad";
-    }>>;
+    includes: z.ZodArray<z.ZodString>;
     secretsPolicy: z.ZodEnum<{
         excluded: "excluded";
         placeholder: "placeholder";
@@ -49,9 +51,9 @@ export declare const bundleManifestSchema: z.ZodObject<{
             agent: "agent";
             command: "command";
             skill: "skill";
+            "claude-md": "claude-md";
             mcp: "mcp";
             hook: "hook";
-            "claude-md": "claude-md";
             bmad: "bmad";
         }>;
         identity: z.ZodString;
@@ -78,10 +80,10 @@ export declare const exportBundleRequestSchema: z.ZodObject<{
     includes: z.ZodArray<z.ZodEnum<{
         agents: "agents";
         hooks: "hooks";
-        commands: "commands";
         skills: "skills";
-        mcp: "mcp";
+        commands: "commands";
         "claude-md": "claude-md";
+        mcp: "mcp";
         bmad: "bmad";
     }>>;
     secretsPolicy: z.ZodEnum<{

package/packages/server/dist/utils/harnessBundleSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harnessBundleSchema.d.ts","sourceRoot":"","sources":["../../src/utils/harnessBundleSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0CxB;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU/B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;iBAEjC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;iBAIpC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;iBAGnC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;iBAEhC,CAAC"}
+{"version":3,"file":"harnessBundleSchema.d.ts","sourceRoot":"","sources":["../../src/utils/harnessBundleSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0CxB;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU/B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;;iBAEjC,CAAC;AAEH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;iBAIpC,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;iBAGnC,CAAC;AAEH,eAAO,MAAM,qBAAqB;;iBAEhC,CAAC"}

package/packages/server/dist/utils/harnessBundleSchema.js

@@ -43,6 +43,16 @@ const bundleItemSchema = z.object({
  * future-version bundles fall through to the AC5.a "futureBundle" branch
  * before this schema is even consulted (the import service inspects the raw
  * JSON's version field first, then runs full Zod validation).
+ *
+ * `includes` is intentionally LOOSE (`z.array(z.string())`) rather than
+ * `z.array(sectionSchema)` so a `bundleVersion === 1` manifest carrying a
+ * future-domain stranger section (e.g. `['claude-md', 'future-section']`)
+ * still parses. The import service's `computePreview` then surfaces unknown
+ * sections via `preview.unknownSections` per AC5.b instead of bailing with
+ * `compatibility: 'malformed'`. Export-request validation
+ * (`exportBundleRequestSchema`) keeps `sectionSchema` strict — we never
+ * accept unknown sections from outbound callers, only tolerate them
+ * inbound.
  */
 export const bundleManifestSchema = z.object({
     bundleVersion: z.literal(HARNESS_BUNDLE_VERSION),
@@ -50,7 +60,7 @@ export const bundleManifestSchema = z.object({
     claudeCodeSpecVersion: z.union([z.string().min(1), z.null()]),
     createdAt: z.string().min(1),
     sourceProjectSlug: z.string().min(1),
-    includes: z.array(sectionSchema),
+    includes: z.array(z.string().min(1)),
     secretsPolicy: secretsPolicySchema,
     pluginDependencies: z.array(pluginRefSchema),
     items: z.array(bundleItemSchema),

package/packages/server/dist/utils/harnessBundleSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"harnessBundleSchema.js","sourceRoot":"","sources":["../../src/utils/harnessBundleSchema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"harnessBundleSchema.js","sourceRoot":"","sources":["../../src/utils/harnessBundleSchema.ts"],"names":[],"mappings":"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"}

package/packages/server/dist/utils/harnessPaths.d.ts

@@ -31,4 +31,44 @@ export declare function resolveHarnessPath(ref: HarnessPathRef): Promise<Resolve
  * project root, so traversal is impossible by construction.
  */
 export declare function resolveProjectClaudeMdPath(projectSlug: string): Promise<ResolvedHarnessPath>;
+/**
+ * Story 30.7 (Task A.5): resolve the project-root `<projectRoot>/.gitignore`
+ * path. Like `resolveProjectClaudeMdPath`, `.gitignore` sits outside the
+ * `.claude/` subtree, so `resolveHarnessPath` cannot reach it. This helper
+ * accepts only `projectSlug` (no caller-supplied relative path), so traversal
+ * is impossible by construction. Used by
+ * `harnessShareScopeService.appendGitignorePattern()` to safely append
+ * patterns like `**\/.claude/**\/*.local.*` when the sibling-save flow detects
+ * the pattern is missing.
+ */
+export declare function resolveProjectGitignorePath(projectSlug: string): Promise<ResolvedHarnessPath>;
+/**
+ * Story 31.1 (Task A.1): resolve the project-root
+ * `<projectRoot>/.bmad-core/core-config.yaml` path. Like
+ * `resolveProjectClaudeMdPath` / `resolveProjectGitignorePath`, the
+ * `.bmad-core/` tree sits OUTSIDE the project's `.claude/` subtree, so
+ * `resolveHarnessPath` would reject it as a traversal. This helper accepts
+ * only `projectSlug` (no caller-supplied relative path), so traversal is
+ * impossible by construction. Used by `bmadCoreConfigService` to read/patch
+ * the single config file the BMad config form edits.
+ */
+export declare function resolveBmadCoreConfigPath(projectSlug: string): Promise<ResolvedHarnessPath>;
+/**
+ * Story 31.2 (Task A.1): resolve the context-builder manifest path
+ * `<projectRoot>/.hammoc/context-builder.json`. Like the `.bmad-core/`
+ * resolver, the `.hammoc/` tree sits OUTSIDE the project's `.claude/` subtree,
+ * so `resolveHarnessPath` would reject it as a traversal. Accepts only
+ * `projectSlug` (no caller-supplied relative path), so traversal is impossible
+ * by construction. Used by `contextBuilderService` as the single manifest R/W
+ * chokepoint (no other module touches this path via `fs`).
+ */
+export declare function resolveContextBuilderManifestPath(projectSlug: string): Promise<ResolvedHarnessPath>;
+/**
+ * Story 31.2 (Task A.1): resolve the generated script path
+ * `<projectRoot>/.hammoc/hooks/context-builder.mjs`. Same traversal-proof
+ * construction as `resolveContextBuilderManifestPath`. The generated `.mjs`
+ * runs standalone at every session start, assembling the `additionalContext`
+ * JSON the SessionStart hook emits.
+ */
+export declare function resolveContextBuilderScriptPath(projectSlug: string): Promise<ResolvedHarnessPath>;
 //# sourceMappingURL=harnessPaths.d.ts.map

package/packages/server/dist/utils/harnessPaths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harnessPaths.d.ts","sourceRoot":"","sources":["../../src/utils/harnessPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAWrE,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED,wFAAwF;AACxF,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBhF;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwC1F;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAyBlG"}
+{"version":3,"file":"harnessPaths.d.ts","sourceRoot":"","sources":["../../src/utils/harnessPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAWrE,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,MAAM,CAO3C;AAED,wFAAwF;AACxF,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBhF;AAED,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwC1F;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAyBlG;AAED;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwBnG;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwBjG;AAED;;;;;;;;GAQG;AACH,wBAAsB,iCAAiC,CACrD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAI9B;AAED;;;;;;GAMG;AACH,wBAAsB,+BAA+B,CACnD,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAI9B"}

package/packages/server/dist/utils/harnessPaths.js

@@ -121,4 +121,127 @@ export async function resolveProjectClaudeMdPath(projectSlug) {
     const absolutePath = path.join(resolvedRoot, 'CLAUDE.md');
     return { resolvedRoot, absolutePath };
 }
+/**
+ * Story 30.7 (Task A.5): resolve the project-root `<projectRoot>/.gitignore`
+ * path. Like `resolveProjectClaudeMdPath`, `.gitignore` sits outside the
+ * `.claude/` subtree, so `resolveHarnessPath` cannot reach it. This helper
+ * accepts only `projectSlug` (no caller-supplied relative path), so traversal
+ * is impossible by construction. Used by
+ * `harnessShareScopeService.appendGitignorePattern()` to safely append
+ * patterns like `**\/.claude/**\/*.local.*` when the sibling-save flow detects
+ * the pattern is missing.
+ */
+export async function resolveProjectGitignorePath(projectSlug) {
+    if (!projectSlug || projectSlug.includes('\0')) {
+        const err = new Error('invalid projectSlug');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    if (projectSlug.includes('..') || projectSlug.includes('/') || projectSlug.includes('\\')) {
+        const err = new Error('projectSlug must not contain path separators');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    let projectRoot;
+    try {
+        projectRoot = await projectService.resolveOriginalPath(projectSlug);
+    }
+    catch (error) {
+        const wrapped = new Error(`Unable to resolve project root for "${projectSlug}": ${error.message}`);
+        wrapped.code = HARNESS_ERRORS.HARNESS_ROOT_MISSING.code;
+        throw wrapped;
+    }
+    const resolvedRoot = path.resolve(projectRoot);
+    const absolutePath = path.join(resolvedRoot, '.gitignore');
+    return { resolvedRoot, absolutePath };
+}
+/**
+ * Story 31.1 (Task A.1): resolve the project-root
+ * `<projectRoot>/.bmad-core/core-config.yaml` path. Like
+ * `resolveProjectClaudeMdPath` / `resolveProjectGitignorePath`, the
+ * `.bmad-core/` tree sits OUTSIDE the project's `.claude/` subtree, so
+ * `resolveHarnessPath` would reject it as a traversal. This helper accepts
+ * only `projectSlug` (no caller-supplied relative path), so traversal is
+ * impossible by construction. Used by `bmadCoreConfigService` to read/patch
+ * the single config file the BMad config form edits.
+ */
+export async function resolveBmadCoreConfigPath(projectSlug) {
+    if (!projectSlug || projectSlug.includes('\0')) {
+        const err = new Error('invalid projectSlug');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    if (projectSlug.includes('..') || projectSlug.includes('/') || projectSlug.includes('\\')) {
+        const err = new Error('projectSlug must not contain path separators');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    let projectRoot;
+    try {
+        projectRoot = await projectService.resolveOriginalPath(projectSlug);
+    }
+    catch (error) {
+        const wrapped = new Error(`Unable to resolve project root for "${projectSlug}": ${error.message}`);
+        wrapped.code = HARNESS_ERRORS.HARNESS_ROOT_MISSING.code;
+        throw wrapped;
+    }
+    const resolvedRoot = path.resolve(projectRoot);
+    const absolutePath = path.join(resolvedRoot, '.bmad-core', 'core-config.yaml');
+    return { resolvedRoot, absolutePath };
+}
+/**
+ * Story 31.2 (Task A.1): resolve the context-builder manifest path
+ * `<projectRoot>/.hammoc/context-builder.json`. Like the `.bmad-core/`
+ * resolver, the `.hammoc/` tree sits OUTSIDE the project's `.claude/` subtree,
+ * so `resolveHarnessPath` would reject it as a traversal. Accepts only
+ * `projectSlug` (no caller-supplied relative path), so traversal is impossible
+ * by construction. Used by `contextBuilderService` as the single manifest R/W
+ * chokepoint (no other module touches this path via `fs`).
+ */
+export async function resolveContextBuilderManifestPath(projectSlug) {
+    const { resolvedRoot } = await resolveHammocRootForProject(projectSlug);
+    const absolutePath = path.join(resolvedRoot, '.hammoc', 'context-builder.json');
+    return { resolvedRoot, absolutePath };
+}
+/**
+ * Story 31.2 (Task A.1): resolve the generated script path
+ * `<projectRoot>/.hammoc/hooks/context-builder.mjs`. Same traversal-proof
+ * construction as `resolveContextBuilderManifestPath`. The generated `.mjs`
+ * runs standalone at every session start, assembling the `additionalContext`
+ * JSON the SessionStart hook emits.
+ */
+export async function resolveContextBuilderScriptPath(projectSlug) {
+    const { resolvedRoot } = await resolveHammocRootForProject(projectSlug);
+    const absolutePath = path.join(resolvedRoot, '.hammoc', 'hooks', 'context-builder.mjs');
+    return { resolvedRoot, absolutePath };
+}
+/**
+ * Shared resolver tail for the two `.hammoc/` helpers above — validates the
+ * slug (no null byte / path separators) and resolves the project root. Returns
+ * `resolvedRoot` = the project root (NOT `.hammoc/`), so each caller appends its
+ * own suffix; this keeps the traversal guard in one place.
+ */
+async function resolveHammocRootForProject(projectSlug) {
+    if (!projectSlug || projectSlug.includes('\0')) {
+        const err = new Error('invalid projectSlug');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    if (projectSlug.includes('..') || projectSlug.includes('/') || projectSlug.includes('\\')) {
+        const err = new Error('projectSlug must not contain path separators');
+        err.code = HARNESS_ERRORS.HARNESS_PATH_DENIED.code;
+        throw err;
+    }
+    let projectRoot;
+    try {
+        projectRoot = await projectService.resolveOriginalPath(projectSlug);
+    }
+    catch (error) {
+        const wrapped = new Error(`Unable to resolve project root for "${projectSlug}": ${error.message}`);
+        wrapped.code = HARNESS_ERRORS.HARNESS_ROOT_MISSING.code;
+        throw wrapped;
+    }
+    const resolvedRoot = path.resolve(projectRoot);
+    return { resolvedRoot, absolutePath: resolvedRoot };
+}
 //# sourceMappingURL=harnessPaths.js.map

package/packages/server/dist/utils/harnessPaths.js.map

@@ -1 +1 @@
-{"version":3,"file":"harnessPaths.js","sourceRoot":"","sources":["../../src/utils/harnessPaths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"harnessPaths.js","sourceRoot":"","sources":["../../src/utils/harnessPaths.ts"],"names":[],"mappings":"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"}

package/packages/server/dist/utils/trailingThrottle.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Trailing-edge throttle (Story 37.8) — paces CLI mirror screen frames so a burst of PTY
+ * redraws (the spinner repaints many times a second) collapses to at most one send per
+ * interval, while still guaranteeing the LATEST frame in the burst is delivered.
+ *
+ * Semantics:
+ *   - `schedule(value)` — leading edge: if nothing fired within the interval, run `fn`
+ *     immediately; otherwise stash `value` as pending and run it once when the interval
+ *     elapses (trailing edge, always the most recent value).
+ *   - `cancel()` — drop any pending value and clear the timer. Called at turn teardown,
+ *     which then sends the final screen directly (outside the throttle) so the last frame
+ *     is never lost to an unelapsed interval.
+ *
+ * Pure / timer-only: no xterm or socket coupling, so it unit-tests with fake timers.
+ */
+export interface TrailingThrottle<T> {
+    schedule(value: T): void;
+    cancel(): void;
+}
+export declare function createTrailingThrottle<T>(intervalMs: number, fn: (value: T) => void): TrailingThrottle<T>;
+//# sourceMappingURL=trailingThrottle.d.ts.map

package/packages/server/dist/utils/trailingThrottle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailingThrottle.d.ts","sourceRoot":"","sources":["../../src/utils/trailingThrottle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACzB,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GACrB,gBAAgB,CAAC,CAAC,CAAC,CAoCrB"}

package/packages/server/dist/utils/trailingThrottle.js

@@ -0,0 +1,36 @@
+export function createTrailingThrottle(intervalMs, fn) {
+    let timer = null;
+    let pending = null;
+    const fire = (value) => {
+        // Open the cool-down window first; a schedule() during it stashes `pending`, which the
+        // trailing timer below flushes. Then run fn.
+        timer = setTimeout(onInterval, intervalMs);
+        fn(value);
+    };
+    function onInterval() {
+        timer = null;
+        if (pending) {
+            const { value } = pending;
+            pending = null;
+            fire(value); // trailing edge — re-opens the window so a steady stream keeps pacing
+        }
+    }
+    return {
+        schedule(value) {
+            if (timer === null) {
+                fire(value); // leading edge — nothing in flight, send immediately
+            }
+            else {
+                pending = { value }; // within the window — keep only the latest
+            }
+        },
+        cancel() {
+            if (timer !== null) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            pending = null;
+        },
+    };
+}
+//# sourceMappingURL=trailingThrottle.js.map

package/packages/server/dist/utils/trailingThrottle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trailingThrottle.js","sourceRoot":"","sources":["../../src/utils/trailingThrottle.ts"],"names":[],"mappings":"AAoBA,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,EAAsB;IAEtB,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,OAAO,GAAwB,IAAI,CAAC;IAExC,MAAM,IAAI,GAAG,CAAC,KAAQ,EAAQ,EAAE;QAC9B,uFAAuF;QACvF,6CAA6C;QAC7C,KAAK,GAAG,UAAU,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;QAC3C,EAAE,CAAC,KAAK,CAAC,CAAC;IACZ,CAAC,CAAC;IAEF,SAAS,UAAU;QACjB,KAAK,GAAG,IAAI,CAAC;QACb,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;YAC1B,OAAO,GAAG,IAAI,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,sEAAsE;QACrF,CAAC;IACH,CAAC;IAED,OAAO;QACL,QAAQ,CAAC,KAAQ;YACf,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,qDAAqD;YACpE,CAAC;iBAAM,CAAC;gBACN,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,2CAA2C;YAClE,CAAC;QACH,CAAC;QACD,MAAM;YACJ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/packages/server/package.json

@@ -1,58 +1,61 @@
-{
-  "name": "@hammoc/server",
-  "version": "1.0.3",
-  "type": "module",
-  "main": "dist/index.js",
-  "scripts": {
-    "dev": "node --import tsx/esm --watch src/dev.ts",
-    "build": "tsc && node -e \"require('fs').cpSync('src/locales','dist/locales',{recursive:true});require('fs').cpSync('src/snippets','dist/snippets',{recursive:true})\"",
-    "start": "cross-env NODE_ENV=production node dist/index.js",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run --exclude '**/**.integration.test.ts'",
-    "test:watch": "vitest --exclude '**/**.integration.test.ts'",
-    "test:coverage": "vitest run --coverage --exclude '**/**.integration.test.ts'",
-    "test:integration": "vitest run src/services/__tests__/chatService.integration.test.ts",
-    "test:all": "vitest run"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.114",
-    "@hammoc/shared": "*",
-    "bcrypt": "^6.0.0",
-    "chokidar": "^5.0.0",
-    "cookie-session": "^2.1.1",
-    "cors": "^2.8.5",
-    "express": "^4.21.0",
-    "helmet": "^8.1.0",
-    "i18next": "^24.2.3",
-    "ignore": "^5.3.2",
-    "js-yaml": "^4.1.1",
-    "jsonc-parser": "^3.3.1",
-    "jszip": "^3.10.1",
-    "multer": "^2.1.1",
-    "node-pty": "^1.0.0",
-    "sharp": "^0.34.5",
-    "simple-git": "^3.27.0",
-    "socket.io": "^4.8.0",
-    "web-push": "^3.6.7",
-    "yaml": "^2.8.3",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/bcrypt": "^6.0.0",
-    "@types/cookie-session": "^2.0.49",
-    "@types/cors": "^2.8.19",
-    "@types/express": "^4.17.25",
-    "@types/express-serve-static-core": "^4.19.8",
-    "@types/js-yaml": "^4.0.9",
-    "@types/multer": "^2.1.0",
-    "@types/node": "^22.0.0",
-    "@types/sharp": "^0.31.1",
-    "@types/supertest": "^6.0.3",
-    "@types/web-push": "^3.6.4",
-    "@vitest/coverage-v8": "^2.0.0",
-    "supertest": "^7.2.2",
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.0",
-    "vitest": "^2.1.9"
-  }
-}
+{
+  "name": "@hammoc/server",
+  "version": "1.0.3",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "node --import tsx/esm --watch src/dev.ts",
+    "build": "tsc && node -e \"require('fs').cpSync('src/locales','dist/locales',{recursive:true});require('fs').cpSync('src/snippets','dist/snippets',{recursive:true})\"",
+    "start": "cross-env NODE_ENV=production node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --exclude '**/**.integration.test.ts'",
+    "test:watch": "vitest --exclude '**/**.integration.test.ts'",
+    "test:coverage": "vitest run --coverage --exclude '**/**.integration.test.ts'",
+    "test:integration": "vitest run src/services/__tests__/chatService.integration.test.ts",
+    "test:all": "vitest run"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.177",
+    "@anthropic-ai/sdk": "^0.100.1",
+    "@hammoc/shared": "*",
+    "@xterm/addon-serialize": "0.14.0",
+    "@xterm/headless": "5.5.0",
+    "bcrypt": "^6.0.0",
+    "chokidar": "^5.0.0",
+    "cookie-session": "^2.1.1",
+    "cors": "^2.8.5",
+    "express": "^4.21.0",
+    "helmet": "^8.1.0",
+    "i18next": "^24.2.3",
+    "ignore": "^5.3.2",
+    "js-yaml": "^4.1.1",
+    "jsonc-parser": "^3.3.1",
+    "jszip": "^3.10.1",
+    "multer": "^2.1.1",
+    "node-pty": "^1.0.0",
+    "sharp": "^0.34.5",
+    "simple-git": "^3.27.0",
+    "socket.io": "^4.8.0",
+    "web-push": "^3.6.7",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bcrypt": "^6.0.0",
+    "@types/cookie-session": "^2.0.49",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.25",
+    "@types/express-serve-static-core": "^4.19.8",
+    "@types/js-yaml": "^4.0.9",
+    "@types/multer": "^2.1.0",
+    "@types/node": "^22.0.0",
+    "@types/sharp": "^0.31.1",
+    "@types/supertest": "^6.0.3",
+    "@types/web-push": "^3.6.4",
+    "@vitest/coverage-v8": "^2.0.0",
+    "supertest": "^7.2.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.9"
+  }
+}

package/packages/server/resources/internals/INDEX.md

@@ -9,7 +9,9 @@ Read individual entries **on demand** when the user's request involves the under
 ## Entries
 
 - [Image Storage](./image-storage.md) — On-disk path and filename scheme for chat-attached images
-- [Harness File Layout](./harness-files.md) — Where `.claude/` items (skills, commands, agents, hooks, MCP servers, `CLAUDE.md`) live on disk, when changes take effect, and how the Secret-on-Shared guard relates to direct file writes
+- [Harness File Layout](./harness-files.md) — Where `.claude/` items (skills, commands, agents, hooks, MCP servers, `CLAUDE.md`) live on disk, when changes take effect, the Context Builder's Hammoc-managed SessionStart files, plugin install-state paths, and how the Secret-on-Shared guard relates to direct file writes
+- [Observability Storage](./observability-storage.md) — Where the MCP call log and exact-token-count cache live, their JSONL/JSON format, body-stripping, and 30-day retention
+- [BMad QA-Fix Marker](./bmad-qa-fix-marker.md) — The `<!-- hammoc:qa-fix -->` story-file convention that drives QA re-review recommendations and the board's "QA Fixed" badge
 
 ## Maintenance
 

package/packages/server/resources/internals/bmad-qa-fix-marker.md

@@ -0,0 +1,32 @@
+# BMad QA-Fix Marker
+
+A Hammoc-specific convention layered on top of standard BMad story files. It lets the project-overview Next Step Recommender (manual §11.5) and the board's "QA Fixed" badge (§10.7) know whether a developer has already addressed the **current** QA gate — without guessing from file modification times (the old, unreliable approach: `review-story` rewrites the story after the gate, which made a freshly-reviewed story look "stale").
+
+## The marker
+
+A single HTML comment inside the story markdown file:
+
+```
+<!-- hammoc:qa-fix gate="<the gate's `updated` value>" applied="true|false" -->
+```
+
+- It is an HTML comment, so standard BMad tooling ignores it and it never changes the story's Status or the gate file.
+- `gate` is the QA gate's `updated:` value — it ties the marker to one specific gate. When QA later re-reviews, the gate's `updated` changes and any marker pointing at the old value becomes stale automatically.
+- `applied="false"` → "QA flagged this gate; a fix is still needed." `applied="true"` → "Dev addressed this gate."
+
+## Who writes it
+
+- **QA review** (Hammoc's bundled `qa-review` snippet) appends `applied="false"` in the story's **QA Results** section when it issues a CONCERNS or FAIL gate.
+- **Apply QA fixes** (the bundled `apply-qa-fixes` snippet) appends `applied="true"` in the story's **Completion Notes** after the fixes are made — without touching Status or the gate file.
+
+If you perform a QA review or apply QA fixes **manually** (not through these snippets), append the matching marker yourself so the recommender and badge stay accurate.
+
+## How it is read
+
+The server (BMad status service) collects all markers in a story and matches them against the **current** gate's `updated` value to derive a per-story `gateFixState`:
+
+- an `applied="true"` marker for the current gate → **`applied`** (Dev done; QA re-review is the next step)
+- only an `applied="false"` marker for the current gate → **`needed`** (Dev must apply fixes)
+- no marker for the current gate → **`undefined`** → the UI offers **both** actions (Apply QA fixes / Request QA review) and lets the user choose, because it can't tell whether fixes were applied (legacy story, external BMad project, or manually-edited gate)
+
+An `applied` marker wins over a `needed` marker for the same gate. The board shows the sky-blue **QA Fixed** badge only when `gateFixState='applied'` for a FAIL/CONCERNS gate.

package/packages/server/resources/internals/harness-files.md

@@ -29,6 +29,28 @@ When the same name (skill, command, agent, hook, MCP server, snippet) exists in
 
 Hammoc-native `%snippets` are a separate layer (see manual §4.6); they live under `<projectRoot>/.hammoc/snippets/` and `<homeDir>/.hammoc/snippets/`, **not** the `.claude/` tree.
 
+## Context Builder generated files (Hammoc-managed)
+
+The Context Builder (manual §12.17) writes two Hammoc-owned files plus one `settings.json` entry:
+
+| File | Role |
+|------|------|
+| `<projectRoot>/.hammoc/context-builder.json` | Manifest — the single source of truth: `enabled` flag, reference-file list, dynamic-variable toggles, recent-commit count, custom-command list |
+| `<projectRoot>/.hammoc/hooks/context-builder.mjs` | Generated Node.js SessionStart hook. Regenerated from the manifest on every change; reads the reference files fresh, recomputes the variables, runs acknowledged custom commands, and prints `{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"…"}}` |
+| `<projectRoot>/.claude/settings.json` → `hooks.SessionStart[]` | Auto-registered entry whose `command` is `node "<absPath>/.hammoc/hooks/context-builder.mjs"` (forward-slash normalized) |
+
+Hammoc recognizes its own SessionStart entry by the `.hammoc/hooks/context-builder.` substring in the command — there is no metadata key. **Do not hand-edit that entry or the `.mjs` script directly**: the Context Builder panel owns them and regenerates the script (overwriting manual edits) on the next save. To change the injected context, edit `context-builder.json` (or use the panel). User-authored SessionStart entries that do not contain the marker substring are left untouched.
+
+## Plugin install state (read-only)
+
+The Marketplace panel (manual §12.19) and the Plugins panel read Claude Code's own plugin bookkeeping under `<homeDir>/.claude/plugins/`:
+
+- `known_marketplaces.json` — registered marketplace repos
+- `marketplaces/<name>/.claude-plugin/marketplace.json` — each marketplace's catalog manifest (`plugins[]`)
+- `installed_plugins.json` — which plugins are installed (used to mark catalog cards "Installed")
+
+Hammoc only **reads** these; installs/uninstalls happen through the interactive `/plugin …` slash commands in a Claude CLI session, after which a file watcher refreshes the cards.
+
 ## Sharing scope
 
 Each file's "share" status is computed from the project's `.gitignore`:

package/packages/server/resources/internals/image-storage.md

@@ -30,6 +30,15 @@ Anything else is rejected at attach time.
 - The chat message references each image via the API URL `/api/projects/<projectSlug>/sessions/<sessionId>/images/<filename>`. That URL is for the **browser** to render thumbnails — it is not a file-system path and Read tools cannot use it directly.
 - To open the file from disk, build the absolute path under `<homeDir>/.claude/projects/...` using the rules above, then call Read with that path.
 
+## Delivery to the model (SDK vs CLI engine)
+
+The on-disk location above is identical for both conversation engines, but how the bytes reach the model differs:
+
+- **SDK engine** — The image is embedded inline in the request as a base64 content block. The model receives it as a vision input directly; no file read occurs.
+- **CLI engine** — The interactive CLI channel carries only text, so the image is referenced **by path** instead. Right after storing, Hammoc grants the model read access to the session image directory (`<homeDir>/.claude/projects/<encoded-project-path>/images/<sessionId>`) via the CLI `--add-dir` flag, then appends an instruction to the prompt telling the model to open the listed absolute path(s) with its Read tool. The grant is scoped to exactly that one image directory (which sits outside the project cwd), and reading an `--add-dir`'d image this way does not raise a permission prompt.
+
+For an agent: in CLI mode an attached image arrives as a literal "use your Read tool to open this file" instruction carrying an absolute path under `.claude/projects/.../images/...` — that path resolves with the rules above.
+
 ## Lifecycle
 
 - Images are written the moment the user sends a message with attachments.

package/packages/server/resources/internals/observability-storage.md

@@ -0,0 +1,23 @@
+# Observability Storage
+
+Hammoc's Observability panel (user-facing, manual §12.18) persists two kinds of data under the user's home `.hammoc` directory. These are **not** under `.claude/` and are reached with direct file reads, not through the harness file service.
+
+`<homeDir>` must be resolved before use — Read does not expand `~`. On Windows that is `C:\Users\<user>\`.
+
+## MCP / tool call log
+
+- **Path:** `<homeDir>/.hammoc/observability/<projectSlug>.jsonl`
+- **Format:** JSON Lines — one tool-call record per line. Each record holds: tool-use id, project slug, session id, server name (parsed from the `mcp__<server>__<tool>` prefix; `null` for built-in tools like Read/Edit/Bash), tool name, start timestamp (epoch ms), duration in ms (`null` if the call never returned), argument byte size, result byte size (`null` if no response), and a success flag (`null` if no response).
+- **Bodies are never written** — only sizes. The log therefore cannot leak file contents or secrets.
+- **Retention:** records older than 30 days (override with the `OBSERVABILITY_RETENTION_DAYS` env var) are pruned on append (throttled to ~30 min) and at server startup.
+- **Written by:** the chat service hooks the existing SDK message stream and appends one record per tool result. "Orphan" calls (started, never returned) are flushed once at turn end with `null` duration / result / success.
+
+## Exact token-count cache
+
+- **Path:** `<homeDir>/.hammoc/observability/token-count-cache.json`
+- **Format:** a JSON object mapping a SHA-256 hash of the input text → official token count.
+- The **Exact count** button calls Anthropic's count-tokens API; the result is cached here keyed by content hash, so re-counting an unchanged file is free and the cache is shared across projects (identical files hash the same).
+
+## Tokenizer preference
+
+- The inline `~` hint is always a byte-size heuristic (size ÷ 4); a tokenizer-grade tier was evaluated but not adopted (it drifted 25–45% from the official count on Claude 4.x). The preference lives in `<homeDir>/.hammoc/preferences.json` under `observabilityTokenizer` and is global (all projects), though its toggle UI sits inside the Observability panel.