{"record":{"id":"5508e0ded8c16288","repo":"ruvnet/ruflo","slug":"label-may-only-contain-a-za-z0-9","errorCode":null,"errorMessage":"label may only contain [A-Za-z0-9_.\\\\-:/@]","messagePattern":"label may only contain \\[A-Za-z0-9_\\.\\\\\\\\-:/@\\]","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/mcp-tools/agenticow-loader.ts","lineNumber":91,"sourceCode":"  return isAbsolute(path) ? path : resolve(getProjectCwd(), path);\n}\n\n/**\n * Lineage manifest companion path. agenticow persists the COW chain\n * (working → checkpoints → base) into `<file>.agenticow.json` next to the\n * `.rvf` data file. Without it, forks/checkpoints are in-memory only and\n * disappear when the AgenticMemory handle closes.\n */\nexport function manifestFor(file: string): string {\n  return `${file}.agenticow.json`;\n}\n\n/** Validate a COW branch/checkpoint label (alnum + a small safe symbol set). */\nexport function validateLabel(label: string): string {\n  if (!label || typeof label !== 'string') throw new Error('label is required');\n  if (label.length > 256) throw new Error('label exceeds 256 chars');\n  if (!/^[A-Za-z0-9_.\\-:/@]+$/.test(label)) {\n    throw new Error('label may only contain [A-Za-z0-9_.\\\\-:/@]');\n  }\n  return label;\n}\n\n/**\n * Open (or create) a memory file, restoring its COW chain from the lineage\n * manifest when one exists. When neither the `.rvf` nor the manifest exists,\n * `dimension` is required to create a fresh base.\n */\nexport async function openWithLineage(api: AgenticowApi, file: string, dimension?: number) {\n  const manifest = manifestFor(file);\n  if (existsSync(manifest)) {\n    return (api.AgenticMemory as any).load(manifest);\n  }\n  const opts: any = {};\n  if (typeof dimension === 'number' && Number.isInteger(dimension) && dimension > 0) {\n    opts.dimension = dimension;\n  } else if (!existsSync(file)) {","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/mcp-tools/agenticow-loader.ts#L73-L109","documentation":"Thrown by validateLabel() (agenticow-loader.ts:91) when a branch/checkpoint label contains characters outside the whitelist regex ^[A-Za-z0-9_.\\-:/@]+$. The whitelist keeps labels filesystem-safe and manifest-JSON-safe since they become keys and path components in the COW lineage manifest.","triggerScenarios":"A label containing spaces ('fix attempt 1'), commas, parentheses, unicode, '#', '+', or any symbol outside A-Z a-z 0-9 _ . - : / @ — submitted to agenticow_branch, agenticow_checkpoint, agenticow_rollback, agenticow_promote, or as an agenticow_speculate candidate label.","commonSituations":"Human-typed labels with spaces or punctuation; labels localized to non-Latin scripts; templated labels that interpolate markdown or user free text.","solutions":["Replace spaces with '-' or '_' and strip punctuation: label.replace(/[^A-Za-z0-9_.\\-:/@]/g, '-')","Use slug/kebab-case labels ('exp-3-nn-branch')","If you need arbitrary text, store it in the record's text field, not the label"],"exampleFix":"// before\nawait callTool('agenticow_checkpoint', { path: p, label: 'fix attempt #1 (auth)' });\n// throws: label may only contain [A-Za-z0-9_.\\-:/@]\n\n// after\nawait callTool('agenticow_checkpoint', { path: p, label: 'fix-attempt-1-auth' });","handlingStrategy":"validation","validationCode":"const LABEL_RE = /^[A-Za-z0-9_.\\-:/@]+$/;\nfunction sanitizeLabel(raw: string): string {\n  return raw.replace(/[^A-Za-z0-9_.\\-:/@]/g, '-').slice(0, 256);\n}\nconst label = sanitizeLabel(userInput);\nif (!LABEL_RE.test(label)) throw new TypeError('label charset invalid');","typeGuard":null,"tryCatchPattern":"try {\n  await callTool('agenticow_checkpoint', args);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('label may only contain')) {\n    args.label = sanitizeLabel(args.label);\n    return callTool('agenticow_checkpoint', args);\n  }\n  throw e;\n}","preventionTips":["Normalize all user-supplied labels to the whitelist charset before they reach the tool","Prefer machine-generated slug labels; treat the label as an identifier, not free text"],"tags":["validation","agenticow","memory","identifier","mcp"],"backgroundTag":"invalid-identifier-characters","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}