@brainervirus/workit-core 0.6.0 → 0.7.0

package/src/core/init.ts

@@ -1,15 +1,24 @@
 import fs from "node:fs";
 import path from "node:path";
-import { configDir } from "./config";
+import { configDir, isConfigObject } from "./config";
 import { PLUGIN_ROOT } from "./scripts";
+import { writeFileExclusive } from "./safe-write";
 import { resolveWorkspace, workspacesPath } from "./workspaces";
+import { applyWorkspaceBranchPolicy } from "./setup";
 import { vcsTokenCreateUrls, vcsVerifyToken } from "./vcs-config";
 import { youTrackTokenCreateUrl, youTrackVerifyToken } from "./youtrack";
 
 const TOKEN_PLACEHOLDER = "YOUR_TOKEN_HERE";
 
+// AR-07/CA-37: a parseable non-object (null, scalar, array) is not a config
+// file — never display it as configured (fail-open) nor as unconfigured.
 const readJson = (p: string): Record<string, any> | null => {
-  try { return JSON.parse(fs.readFileSync(p, "utf8")) as Record<string, any>; } catch { return null; }
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(p, "utf8"));
+    return isConfigObject(parsed) ? (parsed as Record<string, any>) : null;
+  } catch {
+    return null;
+  }
 };
 
 const isPlaceholder = (text: string): boolean =>
@@ -19,7 +28,11 @@ const modeOk = (p: string): boolean =>
   process.platform === "win32" || (fs.statSync(p).mode & 0o777) === 0o600;
 
 const resolvePath = (p: string): string => {
-  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
 };
 
 /** Port of scripts/init/status.sh — filesystem init state. */
@@ -50,11 +63,14 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
       }
     }
     const expanded = tokenFile ? path.resolve(tokenFile) : null;
-    const resolvedTokenFile = expanded && fs.existsSync(expanded)
-      ? resolvePath(expanded)
-      : expanded
-        ? (path.isAbsolute(expanded) ? expanded : path.resolve(configDirPath, expanded))
-        : null;
+    const resolvedTokenFile =
+      expanded && fs.existsSync(expanded)
+        ? resolvePath(expanded)
+        : expanded
+          ? path.isAbsolute(expanded)
+            ? expanded
+            : path.resolve(configDirPath, expanded)
+          : null;
     youtrackConfig = {
       config_edit_path: resolvePath(ytJson),
       baseUrl: base,
@@ -67,8 +83,18 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
       tokenFile: resolvedTokenFile,
       tokenDefaults: ytParsed.tokenDefaults,
       timeLogging: {
-        meetings: { options: meetingIssues, skill: "/wk-meetings", logsTime: true, postsComment: false },
-        taskWork: { issueSource: "active spec/plan **YouTrack:** field or --issue", skill: "/wk-issue-update", logsTime: true, postsComment: true },
+        meetings: {
+          options: meetingIssues,
+          skill: "/wk-meetings",
+          logsTime: true,
+          postsComment: false,
+        },
+        taskWork: {
+          issueSource: "active spec/plan **YouTrack:** field or --issue",
+          skill: "/wk-issue-update",
+          logsTime: true,
+          postsComment: true,
+        },
       },
     };
     youtrackTokenCreate = youTrackTokenCreateUrl().data;
@@ -76,7 +102,18 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
       youtrackConfig.tokenCreate = youtrackTokenCreate;
     }
   } else if (fs.existsSync(ytJson)) {
-    youtrackConfig = { config_edit_path: resolvePath(ytJson), error: "invalid youtrack.json" };
+    // Distinguish parse failure (legacy message, path in config_edit_path) from a
+    // parseable non-object, which gets the shared shape diagnostic with the path.
+    let parseFailed = false;
+    try {
+      JSON.parse(fs.readFileSync(ytJson, "utf8"));
+    } catch {
+      parseFailed = true;
+    }
+    youtrackConfig = {
+      config_edit_path: resolvePath(ytJson),
+      error: parseFailed ? "invalid youtrack.json" : `${resolvePath(ytJson)} is not a JSON object`,
+    };
   }
 
   items.push({
@@ -91,20 +128,28 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
   const ytTokenPath = youtrackConfig?.tokenFile ?? path.join(configDirPath, "youtrack.token");
   const tokenText = fs.existsSync(ytTokenPath) ? fs.readFileSync(ytTokenPath, "utf8").trim() : "";
   const placeholder = fs.existsSync(ytTokenPath) && isPlaceholder(tokenText);
-  const tokenOk = fs.existsSync(ytTokenPath) && modeOk(ytTokenPath) && Boolean(tokenText) && !isPlaceholder(tokenText);
+  const tokenOk =
+    fs.existsSync(ytTokenPath) &&
+    modeOk(ytTokenPath) &&
+    Boolean(tokenText) &&
+    !isPlaceholder(tokenText);
 
   const youtrackTokenItem: Record<string, any> = {
     id: "youtrack_token",
     label: "YouTrack API token (mode 600, not placeholder)",
     ok: tokenOk,
     path: fs.existsSync(ytTokenPath) ? resolvePath(ytTokenPath) : path.resolve(ytTokenPath),
-    token_edit_path: fs.existsSync(ytTokenPath) ? resolvePath(ytTokenPath) : path.resolve(ytTokenPath),
+    token_edit_path: fs.existsSync(ytTokenPath)
+      ? resolvePath(ytTokenPath)
+      : path.resolve(ytTokenPath),
     placeholder,
     fix: `Open ${resolvePath(ytTokenPath)} — replace ${TOKEN_PLACEHOLDER} with your permanent token, save, then /wk-status`,
   };
   if (youtrackTokenCreate) {
-    if (youtrackTokenCreate.createUrl) youtrackTokenItem.token_create_url = youtrackTokenCreate.createUrl;
-    if (youtrackTokenCreate.docsUrl) youtrackTokenItem.token_create_docs_url = youtrackTokenCreate.docsUrl;
+    if (youtrackTokenCreate.createUrl)
+      youtrackTokenItem.token_create_url = youtrackTokenCreate.createUrl;
+    if (youtrackTokenCreate.docsUrl)
+      youtrackTokenItem.token_create_docs_url = youtrackTokenCreate.docsUrl;
     if (youtrackTokenCreate.scopes) youtrackTokenItem.token_scopes = youtrackTokenCreate.scopes;
     if (youtrackTokenCreate.tokenName) youtrackTokenItem.token_name = youtrackTokenCreate.tokenName;
     if (youtrackTokenCreate.steps) youtrackTokenItem.token_create_steps = youtrackTokenCreate.steps;
@@ -181,8 +226,22 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
   for (const k of ["gitlab", "github"]) {
     vcsTokenFiles[k] = String(vcsParsed?.[k]?.tokenFile ?? path.join(configDirPath, `${k}.token`));
   }
-  items.push(tokenItem("gitlab_token", "GitLab token (mode 600, not placeholder)", vcsTokenFiles.gitlab, "gitlab"));
-  items.push(tokenItem("github_token", "GitHub token (mode 600, not placeholder)", vcsTokenFiles.github, "github"));
+  items.push(
+    tokenItem(
+      "gitlab_token",
+      "GitLab token (mode 600, not placeholder)",
+      vcsTokenFiles.gitlab,
+      "gitlab",
+    ),
+  );
+  items.push(
+    tokenItem(
+      "github_token",
+      "GitHub token (mode 600, not placeholder)",
+      vcsTokenFiles.github,
+      "github",
+    ),
+  );
 
   return {
     config_dir: configDirPath,
@@ -196,7 +255,7 @@ export function initStatusData(configDirPath = configDir()): Record<string, any>
 }
 
 /** Port of scripts/init/toolkit-status.sh — filesystem + API health check. */
-export function toolkitStatusData(configDirPath = configDir()): Record<string, any> {
+export async function toolkitStatusData(configDirPath = configDir()): Promise<Record<string, any>> {
   const status = initStatusData(configDirPath);
   const tokenItem = status.items.find((i: Record<string, any>) => i.id === "youtrack_token") ?? {};
   const placeholder = Boolean(tokenItem.placeholder);
@@ -210,15 +269,17 @@ export function toolkitStatusData(configDirPath = configDir()): Record<string, a
 
   const verify = placeholder
     ? { ok: false, error: "token still placeholder YOUR_TOKEN_HERE" }
-    : youTrackVerifyToken();
+    : await youTrackVerifyToken();
   const vcsVerify = vcsPlaceholder
     ? { ok: false, error: "vcs token still placeholder YOUR_TOKEN_HERE" }
-    : vcsVerifyToken();
+    : await vcsVerifyToken();
+  const youTrackHealth = ("data" in verify ? verify.data : verify) as Record<string, any>;
 
   status.youtrack_verify = verify;
-  status.youtrack_ok = placeholder ? false : Boolean((verify as Record<string, any>).ok);
+  status.youtrack_ok = placeholder ? false : Boolean(youTrackHealth.ok);
   status.vcs_verify = vcsVerify;
-  status.vcs_ok = vcsJsonOk && !vcsPlaceholder ? Boolean((vcsVerify as Record<string, any>).ok) : false;
+  status.vcs_ok =
+    vcsJsonOk && !vcsPlaceholder ? Boolean((vcsVerify as Record<string, any>).ok) : false;
 
   const fsReady = status.items.every((i: Record<string, any>) => i.required === false || i.ok);
   status.ready = fsReady && Boolean(status.youtrack_ok) && (!vcsJsonOk || Boolean(status.vcs_ok));
@@ -302,7 +363,10 @@ const vcsJsonContent = (dir: string): Record<string, any> => ({
 });
 
 /** Port of scripts/init/apply.sh — confirmed scaffold actions. */
-export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.env): Record<string, any> {
+export function initApplyData(
+  action: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, any> {
   const dir = String(env.WORKFLOW_TOOLKIT_CONFIG ?? configDir());
   fs.mkdirSync(dir, { recursive: true });
 
@@ -314,7 +378,9 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
     }
     case "youtrack_token_placeholder": {
       const p = path.join(dir, "youtrack.token");
-      fs.writeFileSync(p, TOKEN_PLACEHOLDER + "\n", { encoding: "utf8", mode: 0o600 });
+      // wx + EEXIST-as-preserved (CA-13): an existing real token is never
+      // clobbered — shared with the CLI wizard's ensureToken via safe-write.
+      const preserved = writeFileExclusive(p, TOKEN_PLACEHOLDER + "\n", 0o600) === "preserved";
       const abs = path.resolve(p);
       return {
         action,
@@ -322,6 +388,7 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
         path: abs,
         token_edit_path: abs,
         placeholder: TOKEN_PLACEHOLDER,
+        preserved,
         instruction: `Open ${abs} in your editor, replace YOUR_TOKEN_HERE with your YouTrack permanent token, save, then run /wk-status`,
       };
     }
@@ -329,7 +396,8 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
       const jsonOut = path.join(dir, "youtrack.json");
       const tokenOut = path.join(dir, "youtrack.token");
       fs.writeFileSync(jsonOut, JSON.stringify(youtrackJsonContent(dir), null, 2) + "\n", "utf8");
-      fs.writeFileSync(tokenOut, TOKEN_PLACEHOLDER + "\n", { encoding: "utf8", mode: 0o600 });
+      const preserved =
+        writeFileExclusive(tokenOut, TOKEN_PLACEHOLDER + "\n", 0o600) === "preserved";
       const configPath = path.resolve(jsonOut);
       const tokenPath = path.resolve(tokenOut);
       const prev = process.env.WORKFLOW_YOUTRACK_CONFIG;
@@ -350,6 +418,7 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
           token_create: tokenCreate,
           config_edit_path: configPath,
           placeholder: TOKEN_PLACEHOLDER,
+          preserved,
           youtrack_config: {
             config_edit_path: configPath,
             baseUrl: base,
@@ -360,7 +429,12 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
             locale: cfg.locale,
             tokenCreate,
             timeLogging: {
-              meetings: { issue: meeting, skill: "/wk-meetings", logsTime: true, postsComment: false },
+              meetings: {
+                issue: meeting,
+                skill: "/wk-meetings",
+                logsTime: true,
+                postsComment: false,
+              },
               taskWork: {
                 issueSource: "active spec/plan **YouTrack:** field or --issue",
                 skill: "/wk-issue-update",
@@ -381,8 +455,11 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
       fs.writeFileSync(jsonOut, JSON.stringify(vcsJsonContent(dir), null, 2) + "\n", "utf8");
       const glPath = path.join(dir, "gitlab.token");
       const ghPath = path.join(dir, "github.token");
+      const preservedTokens: string[] = [];
       for (const p of [glPath, ghPath]) {
-        fs.writeFileSync(p, TOKEN_PLACEHOLDER + "\n", { encoding: "utf8", mode: 0o600 });
+        if (writeFileExclusive(p, TOKEN_PLACEHOLDER + "\n", 0o600) === "preserved") {
+          preservedTokens.push(path.resolve(p));
+        }
       }
       const configPath = path.resolve(jsonOut);
       const prev = process.env.WORKFLOW_VCS_CONFIG;
@@ -403,6 +480,7 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
           token_edit_path: activePath,
           token_create_url: active.createUrl,
           token_create_urls: tokenUrls,
+          preserved_tokens: preservedTokens,
           vcs_config: {
             config_edit_path: configPath,
             provider,
@@ -420,22 +498,41 @@ export function initApplyData(action: string, env: NodeJS.ProcessEnv = process.e
         else process.env.WORKFLOW_VCS_CONFIG = prev;
       }
     }
+    case "branch_policy": {
+      const root = env.WORKFLOW_WORKSPACE_ROOT?.trim()
+        ? env.WORKFLOW_WORKSPACE_ROOT
+        : process.cwd();
+      return applyWorkspaceBranchPolicy({ workspace_root: root, env });
+    }
     default: {
-      return { error: `unknown action ${action} (youtrack_scaffold|youtrack_json|youtrack_token_placeholder|vcs_scaffold)` };
+      return {
+        error: `unknown action ${action} (youtrack_scaffold|youtrack_json|youtrack_token_placeholder|vcs_scaffold)`,
+      };
     }
   }
 }
 
 export function initStatus(): Record<string, any> {
   const data = initStatusData();
-  return { ...data, workspaces: { resolved: resolveWorkspace(process.cwd()), path: workspacesPath() } };
+  return {
+    ...data,
+    workspaces: { resolved: resolveWorkspace(process.cwd()), path: workspacesPath() },
+  };
 }
 
-export function toolkitStatus(): Record<string, any> {
+export async function toolkitStatus(): Promise<Record<string, any>> {
   return toolkitStatusData();
 }
 
-export function initApply({ action, confirmed, env }: { action: string; confirmed: boolean; env?: Record<string, string> }): Record<string, any> {
+export function initApply({
+  action,
+  confirmed,
+  env,
+}: {
+  action: string;
+  confirmed: boolean;
+  env?: Record<string, string>;
+}): Record<string, any> {
   if (!confirmed) return { error: "confirmed: true required" };
   return { data: initApplyData(action, env ? { ...process.env, ...env } : process.env) };
 }

package/src/core/logger.ts

@@ -0,0 +1,321 @@
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Secret-safe structured logger (DG-01-DG-03, DG-05, DG-10). Host-neutral:
+// node: builtins only. Never logs prompts, messages, content, raw tool
+// arguments/results, credentials, tokens, authorization headers, issue data,
+// URL queries, home prefixes, or unbounded stacks. Every record is bounded,
+// redacted, rate-limited JSONL under a daily filename.
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export type LogEvent = {
+  level: LogLevel;
+  time: string;
+  message: string;
+  context: Record<string, JsonValue>;
+};
+
+export type LogSink = (event: LogEvent) => void;
+
+export type LoggerOptions = {
+  stateDir?: string;
+  now?: () => Date;
+  appLog?: LogSink;
+  stderr?: LogSink;
+  maxRate?: number;
+  rateWindowMs?: number;
+  maxFieldLength?: number;
+  maxStackLines?: number;
+};
+
+export type Logger = {
+  debug: (message: string, context?: Record<string, unknown>) => void;
+  info: (message: string, context?: Record<string, unknown>) => void;
+  warn: (message: string, context?: Record<string, unknown>) => void;
+  error: (message: string, context?: Record<string, unknown>) => void;
+  guard: <T>(name: string, fn: () => T) => T | undefined;
+};
+
+export const REDACTED = "[REDACTED]";
+
+const DEFAULT_MAX_RATE = 20;
+const DEFAULT_RATE_WINDOW_MS = 1000;
+const DEFAULT_MAX_FIELD_LENGTH = 200;
+const DEFAULT_MAX_STACK_LINES = 30;
+
+const DAY_FILE = /^workit-\d{4}-\d{2}-\d{2}\.jsonl$/;
+const RETAINED_DAYS = 7;
+
+// Home prefixes, URL queries, and inline secret values are redacted inside any
+// string. Key names drive the rest: a field whose name contains a secret or
+// content word is fully replaced, a stack/trace field is line-bounded.
+const SECRET_VALUE = /\b(?:Bearer|Basic|Digest|Token)\s+\S+/gi;
+// Case-insensitive: `Authorization: abc`, `Api-Token=xyz`, `Bearer`-style
+// headers are redacted regardless of casing (D2). The alternation is the same
+// secret vocabulary as SENSITIVE_WORDS, so the over-redaction risk is limited
+// to values next to a secret-ish key — acceptable for a security logger.
+const KEY_EQ_VALUE =
+  /\b([A-Za-z0-9_-]*(?:token|secret|password|passwd|apikey|api[_-]?key|authorization|credential|bearer)[A-Za-z0-9_-]*)([:=]\s*).+/gi;
+const URL_QUERY = /(https?:\/\/[^?#\s]+)\?[^#\s]*/g;
+
+// Split camelCase AND acronym+word compounds (APIToken -> api|token, so the
+// "token" word lands in SENSITIVE_WORDS instead of the whole lowercase
+// compound "apitoken" leaking past it) (D1).
+const splitKey = (key: string): string[] =>
+  key
+    .split(/[_-]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/)
+    .map((word) => word.toLowerCase());
+
+const SENSITIVE_WORDS = new Set([
+  "token",
+  "secret",
+  "password",
+  "passwd",
+  "authorization",
+  "credential",
+  "credentials",
+  "cookie",
+  "api",
+  "apikey",
+  "apitoken",
+  "accesstoken",
+  "clientsecret",
+  "refreshtoken",
+  "key",
+  "bearer",
+  "prompt",
+  "message",
+  "messages",
+  "content",
+  "body",
+  "args",
+  "argument",
+  "result",
+  "results",
+  "output",
+  "issue",
+  "description",
+  "summary",
+  "payload",
+  "script",
+  "command",
+  "text",
+  "query",
+]);
+
+const STACK_WORDS = new Set(["stack", "stacktrace", "trace"]);
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export const resolveStateDir = (): string => {
+  const override = process.env.WORKFLOW_TOOLKIT_STATE;
+  if (override) return override;
+  const home = os.homedir();
+  if (process.env.XDG_STATE_HOME) return path.join(process.env.XDG_STATE_HOME, "workit");
+  switch (os.platform()) {
+    case "darwin":
+      return path.join(home, "Library", "Application Support", "workit");
+    case "win32":
+      return path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "workit");
+    default:
+      return path.join(process.env.HOME ?? home, ".local", "state", "workit");
+  }
+};
+
+type RedactOptions = {
+  maxFieldLength: number;
+  maxStackLines: number;
+};
+
+// The separator lookahead accepts both / and \ so home-relative Windows paths
+// (C:\Users\x\repo) redact too — os.homedir() uses backslashes there.
+const homePattern = new RegExp(
+  `${escapeRegExp(os.homedir())}(?=[/\\\\]|$)|\\$HOME(?=[/\\\\]|$)`,
+  "g",
+);
+
+const applyPatterns = (value: string): string => {
+  let out = value;
+  out = out.replace(SECRET_VALUE, REDACTED);
+  out = out.replace(KEY_EQ_VALUE, "$1$2[REDACTED]");
+  out = out.replace(URL_QUERY, "$1?[REDACTED]");
+  out = out.replace(homePattern, "~");
+  // win32 paths keep backslashes after the ~ substitution (~\repo); normalize
+  // separators so logged paths are portable and match the shell-shaped ~/
+  // form. Other platforms are untouched.
+  if (process.platform === "win32") out = out.replace(/\\/g, "/");
+  return out;
+};
+
+/**
+ * Pattern-only redaction: strips secret value patterns from a string while
+ * preserving its full text — no field-length truncation. The receiver owns its
+ * own size bound (e.g. an MCP error string must stay intact for the client).
+ */
+export const redactSecrets = (value: string): string => applyPatterns(value);
+
+const redactString = (value: string, options: RedactOptions): string => {
+  const out = applyPatterns(value);
+  if (out.length > options.maxFieldLength) {
+    return `${out.slice(0, options.maxFieldLength)}…`;
+  }
+  return out;
+};
+
+const boundStack = (value: unknown, options: RedactOptions): JsonValue => {
+  if (typeof value !== "string") return redact(value, options);
+  const lines = value.split("\n");
+  const kept = lines.slice(0, options.maxStackLines).map(applyPatterns);
+  const dropped = lines.length - kept.length;
+  const body = dropped > 0 ? [...kept, `    ... ${dropped} more`] : kept;
+  return body.join("\n");
+};
+
+export const redact = (value: unknown, options: RedactOptions = DEFAULT_OPTIONS): JsonValue => {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") return redactString(value, options);
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map((entry) => redact(entry, options));
+  if (typeof value === "object") {
+    const out: Record<string, JsonValue> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      const words = splitKey(key);
+      if (words.some((word) => STACK_WORDS.has(word))) out[key] = boundStack(entry, options);
+      else if (words.some((word) => SENSITIVE_WORDS.has(word))) out[key] = REDACTED;
+      else out[key] = redact(entry, options);
+    }
+    return out;
+  }
+  return null;
+};
+
+const DEFAULT_OPTIONS: RedactOptions = {
+  maxFieldLength: DEFAULT_MAX_FIELD_LENGTH,
+  maxStackLines: DEFAULT_MAX_STACK_LINES,
+};
+
+const dailyFileName = (date: Date): string => {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  return `workit-${y}-${m}-${d}.jsonl`;
+};
+
+const pruneOldFiles = (dir: string): void => {
+  try {
+    const files = readdirSync(dir)
+      .filter((name) => DAY_FILE.test(name))
+      .sort()
+      .reverse();
+    for (const file of files.slice(RETAINED_DAYS)) {
+      try {
+        unlinkSync(path.join(dir, file));
+      } catch {
+        // a concurrent prune may already have removed it
+      }
+    }
+  } catch {
+    // logging must never break the host
+  }
+};
+
+export const createLogger = (options: LoggerOptions = {}): Logger => {
+  const stateDir = options.stateDir ?? resolveStateDir();
+  const logDir = path.join(stateDir, "logs");
+  const now = options.now ?? (() => new Date());
+  const maxRate = options.maxRate ?? DEFAULT_MAX_RATE;
+  const rateWindowMs = options.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
+  const redactOptions: RedactOptions = {
+    maxFieldLength: options.maxFieldLength ?? DEFAULT_MAX_FIELD_LENGTH,
+    maxStackLines: options.maxStackLines ?? DEFAULT_MAX_STACK_LINES,
+  };
+
+  let windowStart = 0;
+  const windowCounts: Record<LogLevel, number> = { debug: 0, info: 0, warn: 0, error: 0 };
+
+  const emit = (level: LogLevel, message: string, context?: Record<string, unknown>): void => {
+    const date = now();
+    const elapsed = date.getTime() - windowStart;
+    if (elapsed >= rateWindowMs || windowStart === 0) {
+      windowStart = date.getTime();
+      windowCounts.debug = 0;
+      windowCounts.info = 0;
+      windowCounts.warn = 0;
+      windowCounts.error = 0;
+    }
+    windowCounts[level] += 1;
+    if (windowCounts[level] > maxRate) return;
+
+    // ponytail: per-level budget so an info flood can't starve warn/error
+    // canaries; shared-token budget would need cross-level prioritization.
+    let event: LogEvent | null = null;
+    try {
+      event = {
+        level,
+        time: date.toISOString(),
+        message: redactString(message, redactOptions),
+        context: redact(context ?? {}, redactOptions) as Record<string, JsonValue>,
+      };
+      const line = `${JSON.stringify(event)}\n`;
+      mkdirSync(logDir, { recursive: true, mode: 0o700 });
+      appendFileSync(path.join(logDir, dailyFileName(date)), line, { mode: 0o600 });
+      pruneOldFiles(logDir);
+    } catch {
+      // Serialization (e.g. a circular context) must never throw into the
+      // caller: record a bounded failure event instead.
+      try {
+        event = {
+          level,
+          time: date.toISOString(),
+          message: redactString(message, redactOptions),
+          context: { redaction_failed: true },
+        };
+        mkdirSync(logDir, { recursive: true, mode: 0o700 });
+        appendFileSync(path.join(logDir, dailyFileName(date)), `${JSON.stringify(event)}\n`, {
+          mode: 0o600,
+        });
+      } catch {
+        // logging must never break the host
+      }
+    }
+
+    for (const sink of [options.appLog, options.stderr]) {
+      if (!sink) continue;
+      if (!event) continue;
+      try {
+        sink(event);
+      } catch {
+        // a broken sink must not break the caller
+      }
+    }
+  };
+
+  return {
+    debug: (message, context) => emit("debug", message, context),
+    info: (message, context) => emit("info", message, context),
+    warn: (message, context) => emit("warn", message, context),
+    error: (message, context) => emit("error", message, context),
+    guard: <T>(name: string, fn: () => T): T | undefined => {
+      try {
+        return fn();
+      } catch (err) {
+        emit("warn", "detector_failed", {
+          detector: name,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+      }
+    },
+  };
+};

package/src/core/package-root.ts

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Package-local asset root. Core modules resolve their static assets relative to
+// their own package root (templates/, commands/, skills/, hygiene/). In the
+// monorepo the source package keeps assets at the package root; packaged
+// adapters ship the same content under an explicit `assets/` directory.
+//
+// The walk finds the nearest ancestor directory that owns a package.json, which
+// is the package root for both the monorepo source (packages/<pkg>/src/core/…)
+// and a bundled adapter entry (packages/<pkg>/dist/….js).
+export const packageRoot = (): string => {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const parent = path.dirname(dir);
+    // ponytail: stop at the filesystem root even without an ancestor package.json,
+    // so the upward walk can never loop forever.
+    if (existsSync(path.join(dir, "package.json")) || parent === dir) return dir;
+    dir = parent;
+  }
+};
+
+export const assetRoot = (): string => {
+  const root = packageRoot();
+  const assets = path.join(root, "assets");
+  return existsSync(assets) ? assets : root;
+};

package/src/core/parse-sections.ts

@@ -3,7 +3,7 @@ export function parseSections(stdout: string): Record<string, string> {
   const sections: Record<string, string> = {};
   const parts = stdout.split(/\n## /);
   for (const part of parts.slice(1)) {
-    const nl = part.indexOf('\n');
+    const nl = part.indexOf("\n");
     const title = part.slice(0, nl).trim();
     sections[title] = part.slice(nl + 1).trim();
   }
@@ -12,7 +12,7 @@ export function parseSections(stdout: string): Record<string, string> {
 
 export function parseKeyValueLines(text: string, keys: string[]): Record<string, string> {
   const out: Record<string, string> = {};
-  for (const line of text.split('\n')) {
+  for (const line of text.split("\n")) {
     for (const key of keys) {
       const prefix = `${key}: `;
       if (line.startsWith(prefix)) {